Skip to main content

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

Step 2: Fetch and analyze specification

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

Step 3: Create implementation plan

Step 4: Create implementation plan page

Step 5: Find task database

Step 6: Create implementation tasks

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

Step 7: Begin implementation

Step 8: Track progress

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: