Notion Spec To Implementation

Spec to Implementation

Transforms specifications into actionable implementation plans with progress tracking. Fetches spec documents, extracts requirements, breaks down into tasks, and manages implementation workflow.

Quick Start

When asked to implement a specification:

1. Find spec: Use Notion:notion-search to locate specification page 2. Fetch spec: Use Notion:notion-fetch to read specification content 3. Extract requirements: Parse and structure requirements from spec 4. Create plan: Use Notion:notion-create-pages for implementation plan 5. Find task database: Use Notion:notion-search to locate tasks database 6. Create tasks: Use Notion:notion-create-pages for individual tasks in task database 7. Track progress: Use Notion:notion-update-page to log progress and update status

Implementation Workflow

Step 1: Find the specification

1. Search for spec:
   - Use Notion:notion-search with spec name or topic
   - Apply filters if needed (e.g., created_date_range, teamspace_id)
   - Look for spec title or keyword matches
   - If not found or ambiguous, ask user for spec URL/ID

Example searches:
- "User Authentication spec"
- "Payment Integration specification"
- "Mobile App Redesign PRD"

Step 2: Fetch and analyze specification

1. Fetch spec page:
   - Use Notion:notion-fetch with spec URL/ID from search results
   - Read full content including requirements, design, constraints

2. Parse specification:
   - Identify functional requirements
   - Note non-functional requirements (performance, security, etc.)
   - Extract acceptance criteria
   - Identify dependencies and blockers

See reference/spec-parsing.md for parsing patterns.

Step 3: Create implementation plan

1. Break down into phases/milestones
2. Identify technical approach
3. List required tasks
4. Estimate effort
5. Identify risks

Use implementation plan template (see [reference/standard-implementation-plan.md](reference/standard-implementation-plan.md) or [reference/quick-implementation-plan.md](reference/quick-implementation-plan.md))

Step 4: Create implementation plan page

Use Notion:notion-create-pages:
- Title: "Implementation Plan: [Feature Name]"
- Content: Structured plan with phases, tasks, timeline
- Link back to original spec
- Add to appropriate location (project page, database)

Step 5: Find task database

1. Search for task database:
   - Use Notion:notion-search to find "Tasks" or "Task Management" database
   - Look for engineering/project task tracking system
   - If not found or ambiguous, ask user for database location

2. Fetch database schema:
   - Use Notion:notion-fetch with database URL/ID
   - Get property names, types, and options
   - Identify correct data source from <data-source> tags
   - Note required properties for new tasks

Step 6: Create implementation tasks

For each task in plan:
1. Create task in task database using Notion:notion-create-pages
2. Use parent: { data_source_id: 'collection://...' }
3. Set properties from schema:
   - Name/Title: Task description
   - Status: To Do
   - Priority: Based on criticality
   - Related Tasks: Link to spec and plan
4. Add implementation details in content

See reference/task-creation.md for task patterns.

Step 7: Begin implementation

1. Update task status to "In Progress"
2. Add initial progress note
3. Document approach and decisions
4. Link relevant resources

Step 8: Track progress

Regular updates:
1. Update task properties (status, progress)
2. Add progress notes with:
   - What's completed
   - Current focus
   - Blockers/issues
3. Update implementation plan with milestone completion
4. Link to related work (PRs, designs, etc.)

See reference/progress-tracking.md for tracking patterns.

Spec Analysis Patterns

Functional Requirements: User stories, feature descriptions, workflows, data requirements, integration points

Non-Functional Requirements: Performance targets, security requirements, scalability needs, availability, compliance

Acceptance Criteria: Testable conditions, user validation points, performance benchmarks, completion definitions

See reference/spec-parsing.md for detailed parsing techniques.

Implementation Plan Structure

Plan includes: Overview → Linked Spec → Requirements Summary → Technical Approach → Implementation Phases (Goal, Tasks checklist, Estimated effort) → Dependencies → Risks & Mitigation → Timeline → Success Criteria

See reference/standard-implementation-plan.md for full plan template.

Task Breakdown Patterns

By Component: Database, API endpoints, frontend components, integration, testing By Feature Slice: Vertical slices (auth flow, data entry, report generation) By Priority: P0 (must have), P1 (important), P2 (nice to have)

Progress Logging

Daily Updates (active work): Add progress note with completed items, current focus, blockers Milestone Updates (major progress): Update plan checkboxes, add milestone summary, adjust timeline Status Changes (task transitions): Update properties (In Progress → In Review → Done), add completion notes, link deliverables

Progress Format: Date heading → Completed → In Progress → Next Steps → Blockers → Notes

See reference/progress-tracking.md for detailed patterns.

Linking Spec to Implementation

Forward Links: Update spec page with "Implementation" section linking to plan and tasks Backward Links: Reference spec in plan and tasks with "Specification" section Bidirectional Traceability: Maintain both directions for easy tracking

Implementation Status Tracking

Plan Status: Update with phase completion (✅ Complete, 🔄 In Progress %, ⏳ Not Started) and overall percentage Task Aggregation: Query task database by plan ID to generate summary (complete, in progress, blocked, not started)

Handling Spec Changes

Detection: Fetch updated spec → compare with plan → identify new requirements → assess impact Propagation: Update plan → create new tasks → update affected tasks → add change note → notify via comments Change Log: Track spec evolution with date, what changed, and impact

Common Patterns

Feature Flag: Backend (behind flag) → Testing → Frontend (flagged) → Internal rollout → External rollout Database Migration: Schema design → Migration script → Staging test → Production migration → Validation API Development: API design → Backend implementation → Testing & docs → Client integration → Deployment

Best Practices

1. Always link spec and implementation: Maintain bidirectional references 2. Break down into small tasks: Each task should be completable in 1-2 days 3. Extract clear acceptance criteria: Know when "done" is done 4. Identify dependencies early: Note blockers in plan 5. Update progress regularly: Daily notes for active work 6. Track changes: Document spec updates and their impact 7. Use checklists: Visual progress indicators help everyone 8. Link deliverables: PRs, designs, docs should link back to tasks

Advanced Features

For additional implementation patterns and techniques, see the reference files in reference/.

Common Issues

"Can't find spec": Use Notion:notion-search with spec name/topic, try broader terms, or ask user for URL "Multiple specs found": Ask user which spec to implement or show options "Can't find task database": Search for "Tasks" or "Task Management", or ask user for database location "Spec unclear": Note ambiguities in plan, create clarification tasks "Requirements conflicting": Document conflicts, create decision task "Scope too large": Break into smaller specs/phases

Examples

See examples/ for complete workflows:

• examples/api-feature.md - API feature implementation
• examples/ui-component.md - Frontend component
• examples/database-migration.md - Schema changes

Spec to Implementation Skill Evaluations

Evaluation scenarios for testing the Spec to Implementation skill across different Claude models.

Purpose

These evaluations ensure the Spec to Implementation skill:

• Finds and parses specification pages accurately
• Breaks down specs into actionable implementation plans
• Creates tasks that Claude can implement with clear acceptance criteria
• Tracks progress and updates implementation status
• Works consistently across Haiku, Sonnet, and Opus

Evaluation Files

basic-spec-implementation.json

Tests basic workflow of turning a spec into an implementation plan.

Scenario: Implement user authentication feature from spec Key Behaviors:

• Searches for and finds the authentication spec page
• Fetches spec and extracts requirements
• Parses requirements into phases (setup, core features, polish)
• Creates implementation plan page linked to original spec
• Breaks down into clear phases with deliverables
• Includes timeline and dependencies

spec-to-tasks.json

Tests creating concrete tasks from a specification in a task database.

Scenario: Create tasks from API redesign spec Key Behaviors:

• Finds spec page in Notion
• Extracts specific requirements and acceptance criteria
• Searches for or creates task database
• Fetches task database schema
• Creates multiple tasks with proper properties (Status, Priority, Sprint, etc.)
• Each task has clear title, description, and acceptance criteria
• Tasks have dependencies where appropriate
• Links all tasks back to original spec

Running Evaluations

1. Enable the spec-to-implementation skill 2. Submit the query from the evaluation file 3. Verify the skill finds the spec page via search 4. Check that requirements are accurately parsed 5. Confirm implementation plan is created with phases 6. Verify tasks have clear, implementable acceptance criteria 7. Check that tasks link back to spec 8. Test with Haiku, Sonnet, and Opus

Expected Skill Behaviors

Spec to Implementation evaluations should verify:

Spec Discovery & Parsing

• Searches Notion for specification pages
• Fetches complete spec content
• Extracts all requirements accurately
• Identifies technical dependencies
• Understands acceptance criteria
• Notes any ambiguities or missing details

Implementation Planning

• Creates implementation plan page
• Breaks work into logical phases:
• Phase 1: Foundation/Setup
• Phase 2: Core Implementation
• Phase 3: Testing & Polish
• Includes timeline estimates
• Identifies dependencies between phases
• Links back to original spec

Task Creation

• Finds or identifies task database
• Fetches database schema for property names
• Creates tasks with correct properties
• Each task has:
• Clear, specific title
• Context and description
• Acceptance criteria (checklist format)
• Appropriate priority and status
• Link to spec page
• Tasks are right-sized (not too big, not too small)
• Dependencies between tasks are noted

Progress Tracking

• Implementation plan includes progress markers
• Tasks can be updated as work progresses
• Status updates link to completed work
• Blockers or changes are noted

Creating New Evaluations

When adding Spec to Implementation evaluations:

1. Test different spec types - Features, migrations, refactors, API changes, UI components 2. Vary complexity - Simple 1-phase vs. complex multi-phase implementations 3. Test task granularity - Does it create appropriately-sized tasks? 4. Include edge cases - Vague specs, conflicting requirements, missing details 5. Test database integration - Creating tasks in existing task databases with various schemas 6. Progress tracking - Updating implementation plans as tasks complete

Example Success Criteria

Good (specific, testable):

• "Searches Notion for spec page using feature name"
• "Creates implementation plan with 3 phases: Setup → Core → Polish"
• "Creates 5-8 tasks in task database with properties: Task (title), Status, Priority, Sprint"
• "Each task has acceptance criteria in checklist format (- [ ] ...)"
• "Tasks link back to spec using mention-page tag"
• "Task titles are specific and actionable (e.g., 'Create login API endpoint' not 'Authentication')"

Bad (vague, untestable):

• "Creates good implementation plan"
• "Tasks are well-structured"
• "Breaks down spec appropriately"
• "Links to spec"

Example: API Feature Implementation

User Request

"Create an implementation plan for the User Profile API spec"

Workflow Execution

Step 1: Fetch Specification

Notion:notion-search
query: "User Profile API spec"
query_type: "internal"

Found: "User Profile API Specification" in Engineering Specs

Notion:notion-fetch
id: "user-profile-api-spec-page-id"

Step 2: Parse Specification

Spec Content Extracted:

# User Profile API Specification

## Overview

RESTful API for user profile management

## Requirements

### Functional

- FR-1: Get user profile by ID
- FR-2: Update user profile (name, bio, avatar)
- FR-3: Upload profile avatar
- FR-4: Get user's public profile (limited fields)
- FR-5: Search users by name

### Non-Functional

- NFR-1: Response time < 200ms (p95)
- NFR-2: Support 1000 concurrent users
- NFR-3: Avatar upload < 5MB
- NFR-4: GDPR compliant (data portability)

## API Endpoints

GET /api/v1/users/:id
PUT /api/v1/users/:id
POST /api/v1/users/:id/avatar
GET /api/v1/users/:id/public
GET /api/v1/users/search

## Data Model

- id (UUID)
- email (string, unique)
- name (string)
- bio (text, max 500 chars)
- avatar_url (string)
- created_at (timestamp)
- updated_at (timestamp)

## Security

- Authentication: JWT bearer token
- Authorization: Users can only update own profile
- Rate limiting: 100 req/min per user

## Acceptance Criteria

- AC-1: All endpoints return proper HTTP status codes
- AC-2: Validation errors return 400 with error details
- AC-3: Unauthorized access returns 401
- AC-4: Rate limit exceeded returns 429
- AC-5: Avatar images stored in S3

Step 3: Create Implementation Plan

Notion:notion-create-pages

parent: { page_id: "engineering-plans-parent-id" }

pages: [{
  properties: {
    "title": "Implementation Plan: User Profile API"
  },
  content: "[Implementation plan]"
}]

Implementation Plan Created:

# Implementation Plan: User Profile API

## Overview

Build RESTful API for user profile management with CRUD operations, avatar upload, and search functionality.

## Linked Specification

<mention-page url="...">User Profile API Specification</mention-page>

## Requirements Summary

### Functional Requirements

- ✅ Get user profile (authenticated)
- ✅ Update profile fields (name, bio)
- ✅ Upload avatar with image processing
- ✅ Public profile view (limited fields)
- ✅ User search by name

### Non-Functional Requirements

- **Performance**: < 200ms response time (p95)
- **Scalability**: 1000 concurrent users
- **Storage**: Avatar files < 5MB to S3
- **Compliance**: GDPR data portability

### Acceptance Criteria

- All endpoints with proper status codes
- Input validation with error details
- JWT authentication required
- Rate limiting enforced
- Avatars stored in S3

## Technical Approach

### Architecture

- **Framework**: Express.js (Node.js)
- **Database**: PostgreSQL
- **Storage**: AWS S3 for avatars
- **Cache**: Redis for profile data
- **Search**: PostgreSQL full-text search

### Key Design Decisions

1. **JWT Authentication**: Stateless auth, scales horizontally
2. **S3 for Avatars**: Offload storage, CDN integration ready
3. **Redis Caching**: Reduce DB load for frequently accessed profiles
4. **Rate Limiting**: Token bucket algorithm, per-user limits

## Implementation Phases

### Phase 1: Foundation (Days 1-2)

**Goal**: Set up core infrastructure

**Tasks**:

- [ ] <mention-page url="...">Setup database schema</mention-page>
- [ ] <mention-page url="...">Configure S3 bucket</mention-page>
- [ ] <mention-page url="...">Setup Redis cache</mention-page>
- [ ] <mention-page url="...">Create API scaffolding</mention-page>

**Deliverables**: Working skeleton with DB, storage, cache ready  
**Estimated effort**: 2 days

### Phase 2: Core Endpoints (Days 3-5)

**Goal**: Implement main CRUD operations

**Tasks**:

- [ ] <mention-page url="...">Implement GET user profile</mention-page>
- [ ] <mention-page url="...">Implement PUT update profile</mention-page>
- [ ] <mention-page url="...">Add input validation</mention-page>
- [ ] <mention-page url="...">Add JWT authentication middleware</mention-page>
- [ ] <mention-page url="...">Implement rate limiting</mention-page>

**Deliverables**: Working CRUD operations with auth  
**Estimated effort**: 3 days

### Phase 3: Avatar Upload (Days 6-7)

**Goal**: Avatar management with S3

**Tasks**:

- [ ] <mention-page url="...">Implement avatar upload endpoint</mention-page>
- [ ] <mention-page url="...">Add image validation (size, format)</mention-page>
- [ ] <mention-page url="...">Process and resize images</mention-page>
- [ ] <mention-page url="...">Upload to S3 with signed URLs</mention-page>

**Deliverables**: Avatar upload/update functionality  
**Estimated effort**: 2 days

### Phase 4: Search & Public Profile (Days 8-9)

**Goal**: Complete remaining features

**Tasks**:

- [ ] <mention-page url="...">Implement user search</mention-page>
- [ ] <mention-page url="...">Implement public profile endpoint</mention-page>
- [ ] <mention-page url="...">Add search indexing</mention-page>
- [ ] <mention-page url="...">Optimize search queries</mention-page>

**Deliverables**: Search and public profiles working  
**Estimated effort**: 2 days

### Phase 5: Testing & Optimization (Days 10-12)

**Goal**: Production-ready quality

**Tasks**:

- [ ] <mention-page url="...">Write unit tests</mention-page>
- [ ] <mention-page url="...">Write integration tests</mention-page>
- [ ] <mention-page url="...">Performance testing</mention-page>
- [ ] <mention-page url="...">Security audit</mention-page>
- [ ] <mention-page url="...">API documentation</mention-page>

**Deliverables**: Tested, documented, production-ready API  
**Estimated effort**: 3 days

## Dependencies

### External Dependencies

- AWS S3 bucket created ✅
- Redis instance available ✅
- PostgreSQL database provisioned ✅

### Internal Dependencies

- JWT authentication service (exists)
- User database table (exists)
- Logging infrastructure (exists)

### Blockers

None currently

## Risks & Mitigation

### Risk 1: Image Processing Performance

- **Probability**: Medium
- **Impact**: Medium
- **Mitigation**: Use background job queue for processing, return signed upload URL immediately

### Risk 2: S3 Upload Failures

- **Probability**: Low
- **Impact**: Medium
- **Mitigation**: Implement retry logic with exponential backoff, fallback to local storage temporarily

### Risk 3: Rate Limiting Complexity

- **Probability**: Low
- **Impact**: Low
- **Mitigation**: Use proven library (express-rate-limit with Redis store)

### Risk 4: Search Performance

- **Probability**: Medium
- **Impact**: Medium
- **Mitigation**: Add database indexes, consider Elasticsearch if needed later

## Timeline

| Milestone             | Target Date | Status     |
| --------------------- | ----------- | ---------- |
| Phase 1 Complete      | Oct 16      | ⏳ Planned |
| Phase 2 Complete      | Oct 19      | ⏳ Planned |
| Phase 3 Complete      | Oct 21      | ⏳ Planned |
| Phase 4 Complete      | Oct 23      | ⏳ Planned |
| Phase 5 Complete      | Oct 26      | ⏳ Planned |
| **Production Deploy** | **Oct 28**  | ⏳ Planned |

**Total Duration**: 12 working days (~2.5 weeks)

## Success Criteria

### Technical Success

- [ ] All 5 endpoints implemented and working
- [ ] Response time < 200ms (p95) verified in load testing
- [ ] Handles 1000 concurrent users
- [ ] All acceptance criteria met
- [ ] Test coverage > 80%
- [ ] Security scan passed
- [ ] API documentation complete

### Business Success

- [ ] User profile updates functional
- [ ] Avatar uploads working reliably
- [ ] Search returns relevant results in < 500ms
- [ ] Zero critical bugs in first week

## Resources

### Documentation

- <mention-page url="...">User Profile API Specification</mention-page> (original spec)
- <mention-page url="...">Authentication Service Docs</mention-page>
- <mention-page url="...">AWS S3 Setup Guide</mention-page>

### Related Work

- <mention-page url="...">User Authentication API</mention-page> (similar pattern)
- <mention-page url="...">File Upload Service</mention-page> (avatar upload reference)

### External References

- Express.js best practices
- AWS S3 SDK documentation
- PostgreSQL full-text search guide

## Progress Tracking

### Phase Status

- Phase 1: ⏳ Not Started
- Phase 2: ⏳ Not Started
- Phase 3: ⏳ Not Started
- Phase 4: ⏳ Not Started
- Phase 5: ⏳ Not Started

**Overall Progress**: 0% complete

### Latest Update

_Implementation plan created on October 14, 2025_

Step 4: Find Task Database

Notion:notion-search
query: "Tasks database"
query_type: "internal"

Found: "Engineering Tasks" database

Step 5: Fetch Task Database Schema

Notion:notion-fetch
id: "tasks-database-id"

Schema retrieved:

• Data source: collection://tasks-db-uuid
• Properties: Name (title), Status (select), Priority (select), Related Tasks (relation), Story Points (number), Tags (multi_select)

Step 6: Create Implementation Tasks

Now create tasks for Phase 1:

Task 1: Setup database schema

```` Notion:notion-create-pages

parent: { data_source_id: "collection://tasks-db-uuid" }

pages: [{ properties: { "Name": "Setup database schema for User Profile API", "Status": "To Do", "Priority": "High", "Related Tasks": ["impl-plan-page-id", "spec-page-id"], "Story Points": 3, "Tags": "backend, database, api" }, content: "## Context\nImplementation task for <mention-page url=\"...\">User Profile API Specification</mention-page>\n\nPart of <mention-page url=\"...\">Implementation Plan: User Profile API</mention-page> - Phase 1\n\n## Objective\nCreate database schema for user profile storage\n\n## Requirements\nBased on spec data model:\n- id (UUID, primary key)\n- email (string, unique index)\n- name (string, not null)\n- bio (text, max 500 chars)\n- avatar_url (string, nullable)\n- created_at (timestamp)\n- updated_at (timestamp)\n\n## Acceptance Criteria\n- [ ] Migration file created\n- [ ] Schema includes all required fields\n- [ ] Indexes on email (unique) and name (search)\n- [ ] Constraints validated (bio length, email format)\n- [ ] Migration tested on dev database\n- [ ] Rollback migration created\n\n## Technical Approach\n``sql\nCREATE TABLE user_profiles (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n email VARCHAR(255) UNIQUE NOT NULL,\n name VARCHAR(255) NOT NULL,\n bio TEXT CHECK (length(bio) <= 500),\n avatar_url TEXT,\n created_at TIMESTAMP DEFAULT NOW(),\n updated_at TIMESTAMP DEFAULT NOW()\n);\n\nCREATE INDEX idx_user_profiles_email ON user_profiles(email);\nCREATE INDEX idx_user_profiles_name ON user_profiles USING gin(to_tsvector('english', name));\n`\n\n## Dependencies\n- Blocked By: None\n- Blocks: All Phase 2 tasks\n\n## Estimated Effort\n3 story points (half day)\n" }] ```

_[Create similar tasks for all phases - 20 tasks total]_

Step 7: Link Plan Back to Spec

Notion:notion-update-page
page_id: "user-profile-api-spec-page-id"
command: "insert_content_after"
selection_with_ellipsis: "## Acceptance Criteria..."
new_str: "

---

## Implementation

**Implementation Plan**: <mention-page url=\"...\">Implementation Plan: User Profile API</mention-page>

**Implementation Tasks**: See plan for full task breakdown (20 tasks across 5 phases)

**Status**: Planning complete, ready to start implementation
"

Summary Provided to User

## Implementation Plan Created ✅

### Plan Overview

- **Feature**: User Profile API
- **Duration**: 12 days (~2.5 weeks)
- **Phases**: 5 (Foundation → Core → Avatar → Search → Testing)
- **Tasks**: 20 tasks created
- **Target Launch**: October 28, 2025

### Implementation Phases

**Phase 1: Foundation** (2 days)

- Database schema
- S3 and Redis setup
- API scaffolding

**Phase 2: Core Endpoints** (3 days)

- GET/PUT user profile
- Authentication & validation
- Rate limiting

**Phase 3: Avatar Upload** (2 days)

- Image upload & validation
- S3 integration
- Image processing

**Phase 4: Search & Public Profile** (2 days)

- User search
- Public profile endpoint

**Phase 5: Testing & Optimization** (3 days)

- Unit & integration tests
- Performance testing
- Documentation

### Key Deliverables

- 5 REST API endpoints
- Avatar upload to S3
- User search functionality
- Comprehensive tests
- API documentation

### Links Created

✅ Plan page: <mention-page url="...">Implementation Plan: User Profile API</mention-page>
✅ Spec updated with plan link
✅ 20 tasks created in task database
✅ All tasks linked to plan and spec

### Next Steps

1. Review and approve plan
2. Assign tasks to team members
3. Begin Phase 1 (Foundation)
4. Daily standups for progress tracking

**Ready to start implementation! 🚀**

Key Features Demonstrated

Spec Parsing

• Extracted requirements (functional & non-functional)
• Identified API endpoints
• Noted data model
• Captured acceptance criteria
• Understood security requirements

Implementation Planning

• Broke into logical phases
• Sequenced work appropriately (foundation → features → testing)
• Identified dependencies
• Estimated effort per phase
• Created realistic timeline

Task Creation

• Generated 20 specific tasks
• Each task has context, acceptance criteria, technical approach
• Tasks link to both spec and plan
• Proper dependencies noted

Bidirectional Linking

• Plan links to spec
• Spec updated to link to plan
• Tasks link to both
• Easy navigation between all artifacts

Perfect for: Feature implementation, API development, technical projects

Example: Database Migration Implementation

User Request: "Plan and implement the database migration for user preferences schema"

Workflow

1. Find & Fetch Spec

Notion:notion-search → Found "User Preferences Schema Migration Spec"
Notion:notion-fetch → Extracted requirements

Spec Summary: Migrate from JSON blob to structured schema for better performance and data integrity.

2. Parse Requirements

• Current: JSONB preferences column
• Target: Separate user_preferences and notification_preferences tables
• Must maintain: Backward compatibility during migration
• Performance: Support 1M+ users with zero downtime

3. Create Implementation Plan

Notion:notion-create-pages
pages: [{
  properties: {
    title: "Implementation Plan: User Preferences Migration"
  },
  content: "[Full implementation plan with phases]"
}]

Plan included:

• Phase 1: Create new tables with indexes
• Phase 2: Backfill data from JSONB
• Phase 3: Dual-write mode (both old and new)
• Phase 4: Switch reads to new schema
• Phase 5: Drop old JSONB column

4. Find Task Database & Create Tasks

Notion:notion-search → Found "Engineering Tasks" database
Notion:notion-fetch → Got schema (Task, Status, Priority, Assignee, etc.)

Notion:notion-create-pages
parent: { data_source_id: "collection://xyz" }
pages: [
  {
    properties: {
      "Task": "Write migration SQL scripts",
      "Status": "To Do",
      "Priority": "High",
      "Sprint": "Sprint 25"
    },
    content: "## Context\nPart of User Preferences Migration...\n\n## Acceptance Criteria\n- [ ] Migration script creates tables\n- [ ] Indexes defined..."
  },
  // ... 4 more tasks
]

Tasks created:

1. Write migration SQL scripts 2. Implement backfill job 3. Add dual-write logic to API 4. Update read queries 5. Rollback plan & monitoring

5. Track Progress

Regular updates to implementation plan with status, blockers, and completion notes.

Key Outputs

Implementation Plan Page (linked to spec) 5 Tasks in Database (with dependencies, acceptance criteria) Progress Tracking (updated as work progresses)

Success Factors

• Broke down complex migration into clear phases
• Created tasks with specific acceptance criteria
• Established dependencies (Phase 1 → 2 → 3 → 4 → 5)
• Zero-downtime approach with rollback plan
• Linked all work back to original spec

Example: UI Component Implementation

User Request: "Implement the new search component from the design spec"

Workflow

1. Find Spec

Notion:notion-search
query: "search component design spec"

Found: "Global Search Redesign Spec"

2. Fetch & Parse Spec

Notion:notion-fetch

Requirements:

• Instant search with debounced API calls
• Keyboard navigation (↑↓ arrows, Enter, Esc)
• Recent searches history
• Result categories (pages, people, files)
• Mobile responsive
• Accessibility (ARIA labels, screen reader)

3. Create Implementation Plan

Notion:notion-create-pages

Plan phases:

• Phase 1: Base component structure
• Phase 2: API integration & debouncing
• Phase 3: Keyboard navigation
• Phase 4: Recent searches
• Phase 5: Polish & accessibility

4. Create Tasks

Notion:notion-create-pages (7 tasks)

Tasks:

1. Create SearchInput component 2. Implement useDebounce hook 3. Add keyboard navigation 4. LocalStorage for recent searches 5. Result categorization UI 6. Accessibility audit 7. Mobile responsive styling

5. Implement & Track

As each task completed, updated status and added progress notes with screenshots and implementation details.

Key Outputs

Implementation Plan (linked to design spec) 7 Component Tasks (in Engineering Tasks database) Progress Updates (with code snippets and demo links)

Success Factors

• Clear component breakdown
• Separated concerns (logic, UI, accessibility)
• Each task had acceptance criteria
• Referenced design spec throughout
• Included accessibility from start, not afterthought
• Tracked progress with visual updates

Milestone Summary Template

Use this when completing major phases or milestones.

## Phase [N] Complete: [Date]

### Accomplishments

- [Major item delivered]
- [Major item delivered]

### Deliverables

- <mention-page url="...">Deliverable 1</mention-page>
- [Link to PR/deployment]

### Metrics

- [Relevant metric]
- [Relevant metric]

### Learnings

- [What went well]
- [What to improve]

### Next Phase

Starting [Phase name] on [Date]

Progress Tracking

Update Frequency

Daily Updates

For active implementation work:

What to update:

• Task status if changed
• Add progress note to task
• Update blockers

When:

• End of work day
• After completing significant work
• When encountering blockers

Milestone Updates

For phase/milestone completion:

What to update:

• Mark phase complete in plan
• Add milestone summary
• Update timeline if needed
• Report to stakeholders

When:

• Phase completion
• Major deliverable ready
• Sprint end
• Release

Status Change Updates

For task state transitions:

What to update:

• Task status property
• Add transition note
• Notify relevant people

When:

• Start work (To Do → In Progress)
• Ready for review (In Progress → In Review)
• Complete (In Review → Done)
• Block (Any → Blocked)

Progress Note Format

Daily Progress Note

## Progress: [Date]

### Completed

- [Specific accomplishment with details]
- [Specific accomplishment with details]

### In Progress

- [Current work item]
- Current status: [Percentage or description]

### Next Steps

1. [Next planned action]
2. [Next planned action]

### Blockers

- [Blocker description and who/what needed to unblock]
- Or: None

### Decisions Made

- [Any technical/product decisions]

### Notes

[Additional context, learnings, issues encountered]

Example:

## Progress: Oct 14, 2025

### Completed

- Implemented user authentication API endpoints (login, logout, refresh)
- Added JWT token generation and validation
- Wrote unit tests for auth service (95% coverage)

### In Progress

- Frontend login form integration
- Currently: Form submits but need to handle error states

### Next Steps

1. Complete error handling in login form
2. Add loading states
3. Implement "remember me" functionality

### Blockers

None

### Decisions Made

- Using HttpOnly cookies for refresh tokens (more secure than localStorage)
- Session timeout set to 24 hours based on security review

### Notes

- Found edge case with concurrent login attempts, added to backlog
- Performance of auth check is good (<10ms)

Milestone Summary

## Phase [N] Complete: [Date]

### Overview

[Brief description of what was accomplished in this phase]

### Completed Tasks

- <mention-page url="...">Task 1</mention-page> ✅
- <mention-page url="...">Task 2</mention-page> ✅
- <mention-page url="...">Task 3</mention-page> ✅

### Deliverables

- [Deliverable 1]: [Link/description]
- [Deliverable 2]: [Link/description]

### Key Accomplishments

- [Major achievement]
- [Major achievement]

### Metrics

- [Relevant metric]: [Value]
- [Relevant metric]: [Value]

### Challenges Overcome

- [Challenge and how it was solved]

### Learnings

**What went well**:

- [Success factor]

**What to improve**:

- [Area for improvement]

### Impact on Timeline

- On schedule / [X days ahead/behind]
- Reason: [If deviation, explain why]

### Next Phase

- **Starting**: [Next phase name]
- **Target start date**: [Date]
- **Focus**: [Main objectives]

Updating Implementation Plan

Progress Indicators

Update plan page regularly:

## Status Overview

**Overall Progress**: 45% complete

### Phase Status

- ✅ Phase 1: Foundation - Complete
- 🔄 Phase 2: Core Features - In Progress (60%)
- ⏳ Phase 3: Integration - Not Started

### Task Summary

- ✅ Completed: 12 tasks
- 🔄 In Progress: 5 tasks
- 🚧 Blocked: 1 task
- ⏳ Not Started: 8 tasks

**Last Updated**: [Date]

Task Checklist Updates

Mark completed tasks:

## Implementation Phases

### Phase 1: Foundation

- [x] <mention-page url="...">Database schema</mention-page>
- [x] <mention-page url="...">API scaffolding</mention-page>
- [x] <mention-page url="...">Auth setup</mention-page>

### Phase 2: Core Features

- [x] <mention-page url="...">User management</mention-page>
- [ ] <mention-page url="...">Dashboard</mention-page>
- [ ] <mention-page url="...">Reporting</mention-page>

Timeline Updates

Update milestone dates:

## Timeline

| Milestone | Original | Current | Status                        |
| --------- | -------- | ------- | ----------------------------- |
| Phase 1   | Oct 15   | Oct 14  | ✅ Complete (1 day early)     |
| Phase 2   | Oct 30   | Nov 2   | 🔄 In Progress (3 days delay) |
| Phase 3   | Nov 15   | Nov 18  | ⏳ Planned (adjusted)         |
| Launch    | Nov 20   | Nov 22  | ⏳ Planned (adjusted)         |

**Timeline Status**: Slightly behind due to [reason]

Task Status Tracking

Status Definitions

To Do: Not started

• Task is ready to begin
• Dependencies met
• Assigned (or available)

In Progress: Actively being worked

• Work has started
• Assigned to someone
• Regular updates expected

Blocked: Cannot proceed

• Dependency not met
• External blocker
• Waiting on decision/resource

In Review: Awaiting review

• Work complete from implementer perspective
• Needs code review, QA, or approval
• Reviewers identified

Done: Complete

• All acceptance criteria met
• Reviewed and approved
• Deployed/delivered

Updating Task Status

When updating:

1. Update Status property
2. Add progress note explaining change
3. Update related tasks if needed
4. Notify relevant people via comment

Example:
properties: { "Status": "In Progress" }

Content update:
## Progress: Oct 14, 2025
Started implementation. Set up basic structure and wrote initial tests.

Blocker Tracking

Recording Blockers

When encountering a blocker:

## Blockers

### [Date]: [Blocker Description]

**Status**: 🚧 Active
**Impact**: [What's blocked]
**Needed to unblock**: [Action/person/decision needed]
**Owner**: [Who's responsible for unblocking]
**Target resolution**: [Date or timeframe]

Resolving Blockers

When unblocked:

## Blockers

### [Date]: [Blocker Description]

**Status**: ✅ Resolved on [Date]
**Resolution**: [How it was resolved]
**Impact**: [Any timeline/scope impact]

Escalating Blockers

If blocker needs escalation:

1. Update blocker status in task
2. Add comment tagging stakeholder
3. Update plan with blocker impact
4. Propose mitigation if possible

Metrics Tracking

Velocity Tracking

Track completion rate:

## Velocity

### Week 1

- Tasks completed: 8
- Story points: 21
- Velocity: Strong

### Week 2

- Tasks completed: 6
- Story points: 18
- Velocity: Moderate (1 blocker)

### Week 3

- Tasks completed: 9
- Story points: 24
- Velocity: Strong (blocker resolved)

Quality Metrics

Track quality indicators:

## Quality Metrics

- Test coverage: 87%
- Code review approval rate: 95%
- Bug count: 3 (2 minor, 1 cosmetic)
- Performance: All targets met
- Security: No issues found

Progress Metrics

Quantitative progress:

## Progress Metrics

- Requirements implemented: 15/20 (75%)
- Acceptance criteria met: 42/56 (75%)
- Test cases passing: 128/135 (95%)
- Code complete: 80%
- Documentation: 60%

Stakeholder Communication

Weekly Status Report

## Weekly Status: [Week of Date]

### Summary

[One paragraph overview of progress and status]

### This Week's Accomplishments

- [Key accomplishment]
- [Key accomplishment]
- [Key accomplishment]

### Next Week's Plan

- [Planned work]
- [Planned work]

### Status

- On track / At risk / Behind schedule
- [If at risk or behind, explain and provide mitigation plan]

### Blockers & Needs

- [Active blocker or need for help]
- Or: None

### Risks

- [New or evolving risk]
- Or: None currently identified

Executive Summary

For leadership updates:

## Implementation Status: [Feature Name]

**Overall Status**: 🟢 On Track / 🟡 At Risk / 🔴 Behind

**Progress**: [X]% complete

**Key Updates**:

- [Most important update]
- [Most important update]

**Timeline**: [Status vs original plan]

**Risks**: [Top 1-2 risks]

**Next Milestone**: [Upcoming milestone and date]

Automated Progress Tracking

Query-Based Status

Generate status from task database:

Query task database:
SELECT
  "Status",
  COUNT(*) as count
FROM "collection://tasks-uuid"
WHERE "Related Tasks" CONTAINS 'plan-page-id'
GROUP BY "Status"

Generate summary:
- To Do: 8
- In Progress: 5
- Blocked: 1
- In Review: 2
- Done: 12

Overall: 44% complete (12/28 tasks)

Timeline Calculation

Calculate projected completion:

Average velocity: 6 tasks/week
Remaining tasks: 14
Projected completion: 2.3 weeks from now

Compares to target: [On schedule/Behind/Ahead]

Best Practices

1. Update regularly: Don't let updates pile up 2. Be specific: "Completed login" vs "Made progress" 3. Quantify progress: Use percentages, counts, metrics 4. Note blockers immediately: Don't wait to report blockers 5. Link to work: Reference PRs, deployments, demos 6. Track decisions: Document why, not just what 7. Be honest: Report actual status, not optimistic status 8. Update in one place: Keep implementation plan as source of truth

Progress Update Template

Use this to update progress on implementation plans and tasks.

## Progress: [Date]

### Completed Today

- [Specific item completed]
- [Specific item completed]

### In Progress

- [Current work item and status]

### Next Steps

1. [Next action]
2. [Next action]

### Blockers

- [Blocker description] or None

### Notes

[Additional context, decisions made, issues encountered]

Quick Implementation Plan Template

For simpler features or small changes.

# Implementation: [Feature Name]

## Spec

<mention-page url="...">Specification</mention-page>

## Summary

[Quick description]

## Tasks

- [ ] <mention-page url="...">Task 1</mention-page>
- [ ] <mention-page url="...">Task 2</mention-page>
- [ ] <mention-page url="...">Task 3</mention-page>

## Timeline

Start: [Date]
Target completion: [Date]

## Status

[Update as work progresses]

Specification Parsing

Finding the Specification

Before parsing, locate the spec page:

1. Search for spec:
   Notion:notion-search
   query: "[Feature Name] spec" or "[Feature Name] specification"

2. Handle results:
   - If found → use page URL/ID
   - If multiple → ask user which one
   - If not found → ask user for URL/ID

Example:
Notion:notion-search
query: "User Profile API spec"
query_type: "internal"

Reading Specifications

After finding the spec, fetch it with Notion:notion-fetch:

1. Read the full content 2. Identify key sections 3. Extract structured information 4. Note ambiguities or gaps

Notion:notion-fetch
id: "spec-page-id-from-search"

Common Spec Structures

Requirements-Based Spec

# Feature Spec
## Overview
[Feature description]

## Requirements
### Functional
- REQ-1: [Requirement]
- REQ-2: [Requirement]

### Non-Functional
- PERF-1: [Performance requirement]
- SEC-1: [Security requirement]

## Acceptance Criteria
- AC-1: [Criterion]
- AC-2: [Criterion]

Extract:

• List of functional requirements
• List of non-functional requirements
• List of acceptance criteria

User Story Based Spec

# Feature Spec
## User Stories
### As a [user type]
I want [goal]
So that [benefit]

**Acceptance Criteria**:
- [Criterion]
- [Criterion]

Extract:

• User personas
• Goals/capabilities needed
• Acceptance criteria per story

Technical Design Doc

# Technical Design
## Problem Statement
[Problem description]

## Proposed Solution
[Solution approach]

## Architecture
[Architecture details]

## Implementation Plan
[Implementation approach]

Extract:

• Problem being solved
• Proposed solution approach
• Architectural decisions
• Implementation guidance

Product Requirements Document (PRD)

# PRD: [Feature]
## Goals
[Business goals]

## User Needs
[User problems being solved]

## Features
[Feature list]

## Success Metrics
[How to measure success]

Extract:

• Business goals
• User needs
• Feature list
• Success metrics

Extraction Strategies

Requirement Identification

Look for:

• "Must", "Should", "Will" statements
• Numbered requirements (REQ-1, etc.)
• User stories (As a... I want...)
• Acceptance criteria sections
• Feature lists

Categorization

Group requirements by:

Functional: What the system does

• User capabilities
• System behaviors
• Data operations

Non-Functional: How the system performs

• Performance targets
• Security requirements
• Scalability needs
• Availability requirements
• Compliance requirements

Constraints: Limitations

• Technical constraints
• Business constraints
• Timeline constraints

Priority Extraction

Identify priority indicators:

• "Critical", "Must have", "P0"
• "Important", "Should have", "P1"
• "Nice to have", "Could have", "P2"
• "Future", "Won't have", "P3"

Map to implementation phases based on priority.

Handling Ambiguity

Unclear Requirements

When requirement is ambiguous:

## Clarifications Needed

### [Requirement ID/Description]

**Current text**: "[Ambiguous requirement]"
**Question**: [What needs clarification]
**Impact**: [Why this matters for implementation]
**Assumed for now**: [Working assumption if any]

Create clarification task or add comment to spec.

Missing Information

When critical info is missing:

## Missing Information

- **[Topic]**: Spec doesn't specify [what's missing]
- **Impact**: Blocks [affected tasks]
- **Action**: Need to [how to resolve]

Conflicting Requirements

When requirements conflict:

## Conflicting Requirements

**Conflict**: REQ-1 says [X] but REQ-5 says [Y]
**Impact**: [Implementation impact]
**Resolution needed**: [Decision needed]

Acceptance Criteria Parsing

Explicit Criteria

Direct acceptance criteria:

## Acceptance Criteria
- User can log in with email and password
- System sends confirmation email
- Session expires after 24 hours

Convert to checklist:

• [ ] User can log in with email and password
• [ ] System sends confirmation email
• [ ] Session expires after 24 hours

Implicit Criteria

Derive from requirements:

Requirement: "Users can upload files up to 100MB"

Implied acceptance criteria:
- [ ] Files up to 100MB upload successfully
- [ ] Files over 100MB are rejected with error message
- [ ] Progress indicator shows during upload
- [ ] Upload can be cancelled

Testable Criteria

Ensure criteria are testable:

❌ Not testable: "System is fast" ✓ Testable: "Page loads in < 2 seconds"

❌ Not testable: "Users like the interface" ✓ Testable: "90% of test users complete task successfully"

Technical Detail Extraction

Architecture Information

Extract:

• System components
• Data models
• APIs/interfaces
• Integration points
• Technology choices

Design Decisions

Note:

• Technology selections
• Architecture patterns
• Trade-offs made
• Rationale provided

Implementation Guidance

Look for:

• Suggested approach
• Code examples
• Library recommendations
• Best practices mentioned

Dependency Identification

External Dependencies

From spec, identify:

• Third-party services required
• External APIs needed
• Infrastructure requirements
• Tool/library dependencies

Internal Dependencies

Identify:

• Other features needed first
• Shared components required
• Team dependencies
• Data dependencies

Timeline Dependencies

Note:

• Hard deadlines
• Milestone dependencies
• Sequencing requirements

Scope Extraction

In Scope

What's explicitly included:

• Features to build
• Use cases to support
• Users/personas to serve

Out of Scope

What's explicitly excluded:

• Features deferred
• Use cases not supported
• Edge cases not handled

Assumptions

What's assumed:

• Environment assumptions
• User assumptions
• System state assumptions

Risk Identification

Extract risk information:

Technical Risks

• Unproven technology
• Complex integration
• Performance concerns
• Scalability unknowns

Business Risks

• Market timing
• Resource availability
• Dependency on others

Mitigation Strategies

Note any mitigation approaches mentioned in spec.

Spec Quality Assessment

Evaluate spec completeness:

✓ Good spec:

• Clear requirements
• Explicit acceptance criteria
• Priorities defined
• Risks identified
• Technical approach outlined

⚠️ Incomplete spec:

• Vague requirements
• Missing acceptance criteria
• Unclear priorities
• No risk analysis
• Technical details absent

Document gaps and create clarification tasks.

Parsing Checklist

Before creating implementation plan:

☐ All functional requirements identified ☐ Non-functional requirements noted ☐ Acceptance criteria extracted ☐ Dependencies identified ☐ Risks noted ☐ Ambiguities documented ☐ Technical approach understood ☐ Scope is clear ☐ Priorities are defined

Standard Implementation Plan Template

Use this template for most feature implementations.

# Implementation Plan: [Feature Name]

## Overview

[1-2 sentence feature description and business value]

## Linked Specification

<mention-page url="...">Original Specification</mention-page>

## Requirements Summary

### Functional Requirements

- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

### Non-Functional Requirements

- **Performance**: [Targets]
- **Security**: [Requirements]
- **Scalability**: [Needs]

### Acceptance Criteria

- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

## Technical Approach

### Architecture

[High-level architectural decisions]

### Technology Stack

- Backend: [Technologies]
- Frontend: [Technologies]
- Infrastructure: [Technologies]

### Key Design Decisions

1. **[Decision]**: [Rationale]
2. **[Decision]**: [Rationale]

## Implementation Phases

### Phase 1: Foundation (Week 1)

**Goal**: Set up core infrastructure

**Tasks**:

- [ ] <mention-page url="...">Database schema design</mention-page>
- [ ] <mention-page url="...">API scaffolding</mention-page>
- [ ] <mention-page url="...">Authentication setup</mention-page>

**Deliverables**: Working API skeleton
**Estimated effort**: 3 days

### Phase 2: Core Features (Week 2-3)

**Goal**: Implement main functionality

**Tasks**:

- [ ] <mention-page url="...">Feature A implementation</mention-page>
- [ ] <mention-page url="...">Feature B implementation</mention-page>

**Deliverables**: Core features working
**Estimated effort**: 1 week

### Phase 3: Integration & Polish (Week 4)

**Goal**: Complete integration and refinement

**Tasks**:

- [ ] <mention-page url="...">Frontend integration</mention-page>
- [ ] <mention-page url="...">Testing & QA</mention-page>

**Deliverables**: Production-ready feature
**Estimated effort**: 1 week

## Dependencies

### External Dependencies

- [Dependency 1]: [Status]
- [Dependency 2]: [Status]

### Internal Dependencies

- [Team/component dependency]

### Blockers

- [Known blocker] or None currently

## Risks & Mitigation

### Risk 1: [Description]

- **Probability**: High/Medium/Low
- **Impact**: High/Medium/Low
- **Mitigation**: [Strategy]

### Risk 2: [Description]

- **Probability**: High/Medium/Low
- **Impact**: High/Medium/Low
- **Mitigation**: [Strategy]

## Timeline

| Milestone        | Target Date | Status     |
| ---------------- | ----------- | ---------- |
| Phase 1 Complete | [Date]      | ⏳ Planned |
| Phase 2 Complete | [Date]      | ⏳ Planned |
| Phase 3 Complete | [Date]      | ⏳ Planned |
| Launch           | [Date]      | ⏳ Planned |

## Success Criteria

### Technical Success

- [ ] All acceptance criteria met
- [ ] Performance targets achieved
- [ ] Security requirements satisfied
- [ ] Test coverage > 80%

### Business Success

- [ ] [Business metric 1]
- [ ] [Business metric 2]

## Resources

### Documentation

- <mention-page url="...">Design Doc</mention-page>
- <mention-page url="...">API Spec</mention-page>

### Related Work

- <mention-page url="...">Related Feature</mention-page>

## Progress Tracking

[This section updated regularly]

### Phase Status

- Phase 1: ⏳ Not Started
- Phase 2: ⏳ Not Started
- Phase 3: ⏳ Not Started

**Overall Progress**: 0% complete

### Latest Update: [Date]

[Brief status update]

Task Creation Template

When creating tasks from spec.

# [Task Name]

## Context

Part of implementation for <mention-page url="...">Feature Spec</mention-page>

Implementation plan: <mention-page url="...">Implementation Plan</mention-page>

## Description

[What needs to be done]

## Acceptance Criteria

- [ ] [Criterion 1]
- [ ] [Criterion 2]

## Technical Details

[Technical approach or notes]

## Dependencies

- Blocked by: [Task] or None
- Blocks: [Task] or None

## Resources

- [Link to design]
- [Link to related code]

## Progress

[To be updated during implementation]

Task Creation from Specs

Finding the Task Database

Before creating tasks, locate the task database:

1. Search for task database:
   Notion:notion-search
   query: "Tasks" or "Task Management" or "[Project] Tasks"

2. Fetch database schema:
   Notion:notion-fetch
   id: "database-id-from-search"

3. Identify data source:
   - Look for <data-source url="collection://..."> tags
   - Extract collection ID for parent parameter

4. Note schema:
   - Required properties
   - Property types and options
   - Relation properties for linking

Example:
Notion:notion-search
query: "Engineering Tasks"
query_type: "internal"

Notion:notion-fetch
id: "tasks-database-id"

Result: collection://abc-123-def for use as parent

Task Breakdown Strategy

Size Guidelines

Good task size:

• Completable in 1-2 days
• Single clear deliverable
• Independently testable
• Minimal dependencies

Too large:

• Takes > 3 days
• Multiple deliverables
• Many dependencies
• Break down further

Too small:

• Takes < 2 hours
• Too granular
• Group with related work

Granularity by Phase

Early phases: Larger tasks acceptable

• "Design database schema"
• "Set up API structure"

Middle phases: Medium-sized tasks

• "Implement user authentication"
• "Build dashboard UI"

Late phases: Smaller, precise tasks

• "Fix validation bug in form"
• "Add loading state to button"

Task Creation Pattern

For each requirement or work item:

1. Identify the work
2. Determine task size
3. Create task in database
4. Set properties
5. Write task description
6. Link to spec/plan

Creating Task

Use Notion:notion-create-pages:

parent: {
  type: "data_source_id",
  data_source_id: "collection://tasks-db-uuid"
}

properties: {
  "[Title Property]": "Task: [Clear task name]",
  "Status": "To Do",
  "Priority": "[High/Medium/Low]",
  "[Project/Related]": ["spec-page-id", "plan-page-id"],
  "Assignee": "[Person]" (if known),
  "date:Due Date:start": "[Date]" (if applicable),
  "date:Due Date:is_datetime": 0
}

content: "[Task description using template]"

Task Description Template

# [Task Name]

## Context

Implementation task for <mention-page url="...">Feature Spec</mention-page>

Part of <mention-page url="...">Implementation Plan</mention-page> - Phase [N]

## Objective

[What this task accomplishes]

## Requirements

Based on spec requirements:

- [Relevant requirement 1]
- [Relevant requirement 2]

## Acceptance Criteria

- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]

## Technical Approach

[Suggested implementation approach]

### Components Affected

- [Component 1]
- [Component 2]

### Key Decisions

- [Decision point 1]
- [Decision point 2]

## Dependencies

### Blocked By

- <mention-page url="...">Prerequisite Task</mention-page> or None

### Blocks

- <mention-page url="...">Dependent Task</mention-page> or None

## Resources

- [Link to design mockup]
- [Link to API spec]
- [Link to relevant code]

## Estimated Effort

[Time estimate]

## Progress

[To be updated during implementation]

Task Types

Infrastructure/Setup Tasks

Title: "Setup: [What's being set up]"
Examples:
- "Setup: Configure database connection pool"
- "Setup: Initialize authentication middleware"
- "Setup: Create CI/CD pipeline"

Focus: Getting environment/tooling ready

Feature Implementation Tasks

Title: "Implement: [Feature name]"
Examples:
- "Implement: User login flow"
- "Implement: File upload functionality"
- "Implement: Dashboard widget"

Focus: Building specific functionality

Integration Tasks

Title: "Integrate: [What's being integrated]"
Examples:
- "Integrate: Connect frontend to API"
- "Integrate: Add payment provider"
- "Integrate: Link user profile to dashboard"

Focus: Connecting components

Testing Tasks

Title: "Test: [What's being tested]"
Examples:
- "Test: Write unit tests for auth service"
- "Test: E2E testing for checkout flow"
- "Test: Performance testing for API"

Focus: Validation and quality assurance

Documentation Tasks

Title: "Document: [What's being documented]"
Examples:
- "Document: API endpoints"
- "Document: Setup instructions"
- "Document: Architecture decisions"

Focus: Creating documentation

Bug Fix Tasks

Title: "Fix: [Bug description]"
Examples:
- "Fix: Login error on Safari"
- "Fix: Memory leak in image processing"
- "Fix: Race condition in payment flow"

Focus: Resolving issues

Refactoring Tasks

Title: "Refactor: [What's being refactored]"
Examples:
- "Refactor: Extract auth logic to service"
- "Refactor: Optimize database queries"
- "Refactor: Simplify component hierarchy"

Focus: Code quality improvement

Sequencing Tasks

Critical Path

Identify must-happen-first tasks:

1. Database schema
2. API foundation
3. Core business logic
4. Frontend integration
5. Testing
6. Deployment

Parallel Tracks

Tasks that can happen simultaneously:

Track A: Backend development
- API endpoints
- Business logic
- Database operations

Track B: Frontend development
- UI components
- State management
- Routing

Track C: Infrastructure
- CI/CD setup
- Monitoring
- Documentation

Phase-Based Sequencing

Group by implementation phase:

Phase 1 (Foundation):
- Setup tasks
- Infrastructure tasks

Phase 2 (Core):
- Feature implementation tasks
- Integration tasks

Phase 3 (Polish):
- Testing tasks
- Documentation tasks
- Optimization tasks

Priority Assignment

P0/Critical

• Blocks everything else
• Core functionality
• Security requirements
• Data integrity

P1/High

• Important features
• User-facing functionality
• Performance requirements

P2/Medium

• Nice-to-have features
• Optimizations
• Minor improvements

P3/Low

• Future enhancements
• Edge case handling
• Cosmetic improvements

Estimation

Story Points

If using story points:

• 1 point: Few hours
• 2 points: Half day
• 3 points: Full day
• 5 points: 2 days
• 8 points: 3-4 days (consider breaking down)

Time Estimates

Direct time estimates:

• 2-4 hours: Small task
• 1 day: Medium task
• 2 days: Large task
• 3+ days: Break down further

Estimation Factors

Consider:

• Complexity
• Unknowns
• Dependencies
• Testing requirements
• Documentation needs

Task Relationships

Parent Task Pattern

For large features:

Parent: "Feature: User Authentication"
Children:
- "Setup: Configure auth library"
- "Implement: Login flow"
- "Implement: Password reset"
- "Test: Auth functionality"

Dependency Chain Pattern

For sequential work:

Task A: "Design database schema"
↓ (blocks)
Task B: "Implement data models"
↓ (blocks)
Task C: "Create API endpoints"
↓ (blocks)
Task D: "Integrate with frontend"

Related Tasks Pattern

For parallel work:

Central: "Feature: Dashboard"
Related:
- "Backend API for dashboard data"
- "Frontend dashboard component"
- "Dashboard data caching"

Bulk Task Creation

When creating many tasks:

For each work item in breakdown:
  1. Determine task properties
  2. Create task page
  3. Link to spec/plan
  4. Set relationships

Then:
  1. Update plan with task links
  2. Review sequencing
  3. Assign tasks (if known)

Task Naming Conventions

Be specific: ✓ "Implement user login with email/password" ✗ "Add login"

Include context: ✓ "Dashboard: Add revenue chart widget" ✗ "Add chart"

Use action verbs:

• Implement, Build, Create
• Integrate, Connect, Link
• Fix, Resolve, Debug
• Test, Validate, Verify
• Document, Write, Update
• Refactor, Optimize, Improve

Validation Checklist

Before finalizing tasks:

☐ Each task has clear objective ☐ Acceptance criteria are testable ☐ Dependencies identified ☐ Appropriate size (1-2 days) ☐ Priority assigned ☐ Linked to spec/plan ☐ Proper sequencing ☐ Resources noted