Notion Spec to Toolkit

A practical skill for converting Notion specification documents into implementation plans — covering spec parsing, requirement extraction, task decomposition, dependency mapping, and status tracking that keeps implementation linked to the original specification.

When to Use This Skill

Choose Notion Spec to Toolkit when you need to:

• Convert a Notion spec into actionable implementation tasks
• Map requirements from a spec to development work items
• Track implementation status against spec requirements
• Create linked task lists that reference spec sections
• Keep implementation progress visible alongside the spec

Consider alternatives when:

• You need to write specs from scratch (use a spec writing skill)
• You need project management beyond Notion (use a PM skill)
• You need architecture design (use an architecture skill)

Quick Start

Copy
# Convert a spec to implementation plan
claude "Fetch the 'User Auth Redesign' spec from Notion and convert it into an implementation plan with tasks, dependencies, and estimates."

Copy
# Implementation Plan: User Auth Redesign
**Source Spec**: [User Auth Redesign Spec](notion://page/xxx)
**Target Completion**: Sprint 25 (Dec 27)

## Requirements Extracted

| # | Requirement (from spec) | Priority | Complexity |
|---|------------------------|----------|------------|
| R1| Social login (Google, GitHub) | Must Have | Medium |
| R2| Session-based auth (replace JWT) | Must Have | High |
| R3| Active session management UI | Should Have | Medium |
| R4| 2FA with TOTP | Could Have | Medium |
| R5| Remember me (30-day sessions) | Must Have | Low |

## Task Breakdown

### Phase 1: Core Auth (Sprint 24)
| Task | Spec Req | Depends On | Estimate | Owner |
|------|----------|------------|----------|-------|
| Set up Redis session store | R2 | — | 2h | — |
| Replace JWT middleware with session | R2 | T1 | 4h | — |
| Implement Google OAuth2 flow | R1 | T2 | 4h | — |
| Implement GitHub OAuth2 flow | R1 | T2 | 3h | — |
| Add "Remember me" cookie config | R5 | T2 | 1h | — |

### Phase 2: Session Management (Sprint 25)
| Task | Spec Req | Depends On | Estimate | Owner |
|------|----------|------------|----------|-------|
| Build active sessions API endpoint | R3 | T2 | 3h | — |
| Create session management UI | R3 | T6 | 4h | — |
| Add "Sign out everywhere" feature | R3 | T6 | 2h | — |

### Phase 3: 2FA (Sprint 26, if time permits)
| Task | Spec Req | Depends On | Estimate | Owner |
|------|----------|------------|----------|-------|
| TOTP secret generation | R4 | T2 | 3h | — |
| QR code enrollment flow | R4 | T9 | 4h | — |
| 2FA verification middleware | R4 | T9 | 3h | — |

## Dependency Graph
T1 → T2 → T3, T4, T5 (parallel)
T2 → T6 → T7, T8 (parallel)
T2 → T9 → T10 → T11

Core Concepts

Spec-to-Task Pipeline

Step	Input	Output
Fetch Spec	Notion page ID/search	Raw spec content
Parse Reqs	Spec content	Numbered requirements
Prioritize	Requirements list	MoSCoW categorization
Decompose	Prioritized requirements	Task breakdown
Map Dependencies	Task list	Dependency graph
Estimate	Tasks with dependencies	Time estimates
Track	Implementation progress	Status-linked tasks

Requirement Extraction Patterns

Copy
## Identifying Requirements in Specs

### Explicit Requirements
"The system SHALL support Google OAuth2 login"
→ R: Support Google OAuth2 login (Must Have)

### Implicit Requirements
"Users should be able to manage their sessions"
→ R: Active session listing (Should Have)
→ R: Session revocation (Should Have)
→ R: Session details display (Should Have)

### Non-Functional Requirements
"Login must complete within 3 seconds"
→ R: Login latency < 3 seconds (Must Have, NFR)

### Out of Scope (Noted)
"Future: biometric authentication"
→ Not included in current implementation plan

Configuration

Parameter	Description	Example
spec_page_id	Notion page containing the spec	"notion-page-uuid"
task_database	Notion database for generated tasks	"tasks-db-uuid"
priority_method	How to categorize priorities	"moscow" / "p0-p3"
estimate_unit	Time estimation unit	"hours" / "points"
link_to_spec	Link tasks back to spec sections	true

Best Practices

1. Number every requirement from the spec — Assign R1, R2, R3 identifiers to each requirement. Every task should reference its parent requirement. This traceability lets you verify that the implementation covers the entire spec and nothing was missed.

2. Distinguish must-have from nice-to-have before estimating — Estimate only must-have items first to verify they fit within the timeline. Then layer in should-have and could-have items. This prevents committing to a scope that can't be delivered.

3. Link tasks back to the spec page with inline references — Each task's description should link to the specific section of the Notion spec it implements. When requirements change, developers can click through to the source of truth.

4. Update implementation status in both the task database and the spec — Add a "Implementation Status" property to the spec page that rolls up task completion. Stakeholders reading the spec should see delivery status without checking the task board.

5. Flag spec ambiguities as tasks — When a spec requirement is vague ("improve performance"), create a clarification task before creating implementation tasks. Building on ambiguous requirements wastes engineering time.

Common Issues

Spec changes after implementation starts — Specs evolve, but implementation plans don't auto-update. When the spec changes, review the task breakdown for impact. Add new tasks, remove obsolete ones, and re-estimate affected items.

Task granularity is inconsistent — Some tasks are "Set up Redis" (2 hours) while others are "Build the auth system" (40 hours). Normalize to 2-8 hour tasks. Anything larger should be decomposed further.

Implementation diverges from spec without updating either — Developers make implementation decisions that differ from the spec but don't update either document. Require that any deviation from the spec is documented as a decision in the task and reflected back in the spec.