RomanNum3ral
/
anthropic-skills
mirror of https://github.com/anthropics/skills.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add LICENSE.txt and supporting files for notion-spec-to-implementation skill

This commit is contained in:
mrdesouzaphd-cmyk 2026-06-02 06:09:36 -04:00
parent 2371bb128f
commit 76bb37d15b
16 changed files with 2723 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

202
skills/notion-spec-to-implementation/LICENSE.txt Normal file
View File

@ -0,0 +1,202 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright 2026 Anthropic, PBC.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

215
skills/notion-spec-to-implementation/SKILL.md
View File

@ -11,56 +11,209 @@ Transforms specifications into actionable implementation plans with progress tra
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
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
7. **Update spec**: Link implementation plan back to specification
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
## Task Structure
## Implementation Workflow
Each task should include:
- Title (clear, actionable)
- Description (what needs to be done)
- Acceptance criteria (how to verify completion)
- Dependencies (what must be done first)
- Status (Not Started / In Progress / Complete / Blocked)
- Estimated effort (story points or hours)
### 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](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](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](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](reference/spec-parsing.md) for detailed parsing techniques.
## Implementation Plan Structure
The implementation plan should include:
- Phases with milestones
- Tasks organized by phase
- Dependencies between tasks
- Progress tracking (percentage complete)
- Links back to specification
**Plan includes**: Overview → Linked Spec → Requirements Summary → Technical Approach → Implementation Phases (Goal, Tasks checklist, Estimated effort) → Dependencies → Risks & Mitigation → Timeline → Success Criteria
## Bidirectional Linking
See [reference/standard-implementation-plan.md](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](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
## Progress Tracking
## Implementation Status Tracking
**Plan Status**: Update with phase completion (Complete, In Progress %, Not Started) and overall percentage
**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)
## Change Management
## 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
**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 Integration**: Contract definition > Mock implementation > Real implementation > Testing > Documentation
**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
## Notes
This skill uses Notion MCP integration. The Notion workspace must be connected and accessible for the skill to function.
## 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/](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/](examples/) for complete workflows:
- [examples/api-feature.md](examples/api-feature.md) - API feature implementation
- [examples/ui-component.md](examples/ui-component.md) - Frontend component
- [examples/database-migration.md](examples/database-migration.md) - Schema changes

120
skills/notion-spec-to-implementation/evaluations/README.md Normal file
View File

@ -0,0 +1,120 @@
# 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"

32
skills/notion-spec-to-implementation/evaluations/basic-spec-implementation.json Normal file
View File

@ -0,0 +1,32 @@
{
"name": "Create Implementation Plan from Spec",
"skills": ["spec-to-implementation"],
"query": "Create an implementation plan for the User Authentication spec page",
"expected_behavior": [
"Step 1: Uses Notion:notion-search to find 'User Authentication spec' with keywords like 'User Authentication' or 'auth spec'",
"Step 2: If not found or ambiguous, asks user for spec page URL/ID",
"Step 3: Fetches spec page using Notion:notion-fetch with URL/ID from search results",
"Step 4: Parses spec using patterns from reference/spec-parsing.md to extract requirements, acceptance criteria, constraints",
"Step 5: Identifies functional requirements (user stories, features, workflows) and non-functional requirements (performance, security)",
"Step 6: Creates implementation plan following structure from reference/templates.md",
"Step 7: Includes sections: Overview, Linked Spec, Requirements Summary, Technical Approach, Implementation Phases",
"Step 8: Breaks work into logical phases with Goal, Tasks checklist, Estimated effort per phase",
"Step 9: Identifies dependencies and risks from spec content",
"Step 10: Links plan back to original spec page using <mention-page url='...'>",
"Step 11: Creates plan page using Notion:notion-create-pages with appropriate title (e.g., 'Implementation Plan: User Authentication')",
"Step 12: Places plan appropriately (asks user or suggests under project/spec parent)"
],
"success_criteria": [
"Spec is found using Notion:notion-search before attempting to fetch (or user is asked for URL if not found)",
"Spec is fetched using Notion:notion-fetch with correct URL/ID from search results",
"Plan includes clear overview and spec link with mention-page tag",
"Requirements are extracted from actual spec content (not generic) using spec-parsing patterns",
"Work is broken into multiple phases (typically 3-5) following template structure",
"Each phase has Goal, Tasks (as checkboxes), and Estimated effort",
"Dependencies and risks sections are included with specific details from spec",
"Plan follows Implementation Plan structure from reference/templates.md",
"Success criteria or acceptance criteria from spec are referenced in plan",
"Uses correct tool names and sequence: Notion:notion-search → Notion:notion-fetch → Notion:notion-create-pages"
]
}

35
skills/notion-spec-to-implementation/evaluations/spec-to-tasks.json Normal file
View File

@ -0,0 +1,35 @@
{
"name": "Create Tasks from Specification",
"skills": ["spec-to-implementation", "task-manager"],
"query": "Read the Payment Integration spec and create implementation tasks in our Tasks database",
"expected_behavior": [
"Step 1: Uses Notion:notion-search to find Payment Integration spec or asks for URL",
"Step 2: Fetches spec page using Notion:notion-fetch to read full content",
"Step 3: Parses spec using reference/spec-parsing.md patterns to identify work items",
"Step 4: Breaks down into appropriately-sized tasks using breakdown patterns from reference/task-creation.md",
"Step 5: Uses Notion:notion-search to find Tasks database location",
"Step 6: Fetches Tasks database using Notion:notion-fetch to get schema, property names, and data sources",
"Step 7: Identifies correct data source from <data-source> tags in fetch results",
"Step 8: Optionally creates implementation plan page first (recommended per workflow)",
"Step 9: For each task - creates task page using Notion:notion-create-pages with parent: { data_source_id: 'collection://...' }",
"Step 10: Sets task properties from schema: Title, Status (To Do), Priority, Related Tasks (link to spec)",
"Step 11: Includes task description with context, acceptance criteria from spec, dependencies",
"Step 12: Links tasks to spec page using <mention-page> and to each other for dependencies",
"Step 13: Sequences tasks appropriately (setup → implementation → testing per reference/task-creation.md)",
"Step 14: Reports summary: 'Created X tasks for Payment Integration: [task list with links]'"
],
"success_criteria": [
"Spec is found using Notion:notion-search before attempting to fetch",
"Task database is found using Notion:notion-search before attempting to fetch schema",
"Database schema is fetched and data source identified from <data-source> tags",
"Multiple tasks created (at least 3-5) covering spec scope",
"Tasks are right-sized per reference/task-creation.md (1-2 days each)",
"Each task has clear acceptance criteria extracted from spec",
"Tasks are properly sequenced with dependencies using relation properties",
"All tasks link back to original spec using mention-page tags",
"Task properties match exact schema from fetched database",
"Tasks use correct parent (data_source_id: 'collection://...') for database placement",
"Uses correct tool names and sequence: Notion:notion-search (2x) → Notion:notion-fetch (2x) → Notion:notion-create-pages (Nx)"
]
}

461
skills/notion-spec-to-implementation/examples/api-feature.md Normal file
View File

@ -0,0 +1,461 @@
# 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:**
```markdown
# 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:**
```markdown
# 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
```markdown
## 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

81
skills/notion-spec-to-implementation/examples/database-migration.md Normal file
View File

@ -0,0 +1,81 @@
# 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

68
skills/notion-spec-to-implementation/examples/ui-component.md Normal file
View File

@ -0,0 +1,68 @@
# 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

27
skills/notion-spec-to-implementation/reference/milestone-summary-template.md Normal file
View File

@ -0,0 +1,27 @@
# Milestone Summary Template
Use this when completing major phases or milestones.
```markdown
## 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]
```

458
skills/notion-spec-to-implementation/reference/progress-tracking.md Normal file
View File

@ -0,0 +1,458 @@
# 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
```markdown
## 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:
```markdown
## 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
```markdown
## 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:
```markdown
## 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:
```markdown
## 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:
```markdown
## 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:
```markdown
## 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:
```markdown
## 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:
```markdown
## 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:
```markdown
## 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:
```markdown
## 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
```markdown
## 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:
```markdown
## 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

25
skills/notion-spec-to-implementation/reference/progress-update-template.md Normal file
View File

@ -0,0 +1,25 @@
# Progress Update Template
Use this to update progress on implementation plans and tasks.
```markdown
## 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]
```

26
skills/notion-spec-to-implementation/reference/quick-implementation-plan.md Normal file
View File

@ -0,0 +1,26 @@
# Quick Implementation Plan Template
For simpler features or small changes.
```markdown
# 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]
```

383
skills/notion-spec-to-implementation/reference/spec-parsing.md Normal file
View File

@ -0,0 +1,383 @@
# 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:
```markdown
## 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:
```markdown
## 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:
```markdown
## 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

146
skills/notion-spec-to-implementation/reference/standard-implementation-plan.md Normal file
View File

@ -0,0 +1,146 @@
# Standard Implementation Plan Template
Use this template for most feature implementations.
```markdown
# 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]
```

34
skills/notion-spec-to-implementation/reference/task-creation-template.md Normal file
View File

@ -0,0 +1,34 @@
# Task Creation Template
When creating tasks from spec.
```markdown
# [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]
```

441
skills/notion-spec-to-implementation/reference/task-creation.md Normal file
View File

@ -0,0 +1,441 @@
# 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
```markdown
# [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