From 76bb37d15bf4e89e18694571158f0f4fcd55d9f5 Mon Sep 17 00:00:00 2001 From: mrdesouzaphd-cmyk <239899238+mrdesouzaphd-cmyk@users.noreply.github.com> Date: Tue, 2 Jun 2026 06:09:36 -0400 Subject: [PATCH] Add LICENSE.txt and supporting files for notion-spec-to-implementation skill --- .../notion-spec-to-implementation/LICENSE.txt | 202 ++++++++ skills/notion-spec-to-implementation/SKILL.md | 215 ++++++-- .../evaluations/README.md | 120 +++++ .../basic-spec-implementation.json | 32 ++ .../evaluations/spec-to-tasks.json | 35 ++ .../examples/api-feature.md | 461 ++++++++++++++++++ .../examples/database-migration.md | 81 +++ .../examples/ui-component.md | 68 +++ .../reference/milestone-summary-template.md | 27 + .../reference/progress-tracking.md | 458 +++++++++++++++++ .../reference/progress-update-template.md | 25 + .../reference/quick-implementation-plan.md | 26 + .../reference/spec-parsing.md | 383 +++++++++++++++ .../reference/standard-implementation-plan.md | 146 ++++++ .../reference/task-creation-template.md | 34 ++ .../reference/task-creation.md | 441 +++++++++++++++++ 16 files changed, 2723 insertions(+), 31 deletions(-) create mode 100644 skills/notion-spec-to-implementation/LICENSE.txt create mode 100644 skills/notion-spec-to-implementation/evaluations/README.md create mode 100644 skills/notion-spec-to-implementation/evaluations/basic-spec-implementation.json create mode 100644 skills/notion-spec-to-implementation/evaluations/spec-to-tasks.json create mode 100644 skills/notion-spec-to-implementation/examples/api-feature.md create mode 100644 skills/notion-spec-to-implementation/examples/database-migration.md create mode 100644 skills/notion-spec-to-implementation/examples/ui-component.md create mode 100644 skills/notion-spec-to-implementation/reference/milestone-summary-template.md create mode 100644 skills/notion-spec-to-implementation/reference/progress-tracking.md create mode 100644 skills/notion-spec-to-implementation/reference/progress-update-template.md create mode 100644 skills/notion-spec-to-implementation/reference/quick-implementation-plan.md create mode 100644 skills/notion-spec-to-implementation/reference/spec-parsing.md create mode 100644 skills/notion-spec-to-implementation/reference/standard-implementation-plan.md create mode 100644 skills/notion-spec-to-implementation/reference/task-creation-template.md create mode 100644 skills/notion-spec-to-implementation/reference/task-creation.md diff --git a/skills/notion-spec-to-implementation/LICENSE.txt b/skills/notion-spec-to-implementation/LICENSE.txt new file mode 100644 index 00000000..4f881c52 --- /dev/null +++ b/skills/notion-spec-to-implementation/LICENSE.txt @@ -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. \ No newline at end of file diff --git a/skills/notion-spec-to-implementation/SKILL.md b/skills/notion-spec-to-implementation/SKILL.md index 33148365..579fb33d 100644 --- a/skills/notion-spec-to-implementation/SKILL.md +++ b/skills/notion-spec-to-implementation/SKILL.md @@ -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 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 + diff --git a/skills/notion-spec-to-implementation/evaluations/README.md b/skills/notion-spec-to-implementation/evaluations/README.md new file mode 100644 index 00000000..13dadab8 --- /dev/null +++ b/skills/notion-spec-to-implementation/evaluations/README.md @@ -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" + diff --git a/skills/notion-spec-to-implementation/evaluations/basic-spec-implementation.json b/skills/notion-spec-to-implementation/evaluations/basic-spec-implementation.json new file mode 100644 index 00000000..90407514 --- /dev/null +++ b/skills/notion-spec-to-implementation/evaluations/basic-spec-implementation.json @@ -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 ", + "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" + ] +} + diff --git a/skills/notion-spec-to-implementation/evaluations/spec-to-tasks.json b/skills/notion-spec-to-implementation/evaluations/spec-to-tasks.json new file mode 100644 index 00000000..4da86fb5 --- /dev/null +++ b/skills/notion-spec-to-implementation/evaluations/spec-to-tasks.json @@ -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 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 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 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)" + ] +} + diff --git a/skills/notion-spec-to-implementation/examples/api-feature.md b/skills/notion-spec-to-implementation/examples/api-feature.md new file mode 100644 index 00000000..51df2365 --- /dev/null +++ b/skills/notion-spec-to-implementation/examples/api-feature.md @@ -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 +User Profile API Specification + +## 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**: +- [ ] Setup database schema +- [ ] Configure S3 bucket +- [ ] Setup Redis cache +- [ ] Create API scaffolding + +**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**: +- [ ] Implement GET user profile +- [ ] Implement PUT update profile +- [ ] Add input validation +- [ ] Add JWT authentication middleware +- [ ] Implement rate limiting + +**Deliverables**: Working CRUD operations with auth +**Estimated effort**: 3 days + +### Phase 3: Avatar Upload (Days 6-7) +**Goal**: Avatar management with S3 + +**Tasks**: +- [ ] Implement avatar upload endpoint +- [ ] Add image validation (size, format) +- [ ] Process and resize images +- [ ] Upload to S3 with signed URLs + +**Deliverables**: Avatar upload/update functionality +**Estimated effort**: 2 days + +### Phase 4: Search & Public Profile (Days 8-9) +**Goal**: Complete remaining features + +**Tasks**: +- [ ] Implement user search +- [ ] Implement public profile endpoint +- [ ] Add search indexing +- [ ] Optimize search queries + +**Deliverables**: Search and public profiles working +**Estimated effort**: 2 days + +### Phase 5: Testing & Optimization (Days 10-12) +**Goal**: Production-ready quality + +**Tasks**: +- [ ] Write unit tests +- [ ] Write integration tests +- [ ] Performance testing +- [ ] Security audit +- [ ] API documentation + +**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 +- User Profile API Specification (original spec) +- Authentication Service Docs +- AWS S3 Setup Guide + +### Related Work +- User Authentication API (similar pattern) +- File Upload Service (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 User Profile API Specification\n\nPart of Implementation Plan: User Profile API - 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**: Implementation Plan: User Profile API + +**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: Implementation Plan: User Profile API +✅ 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 + diff --git a/skills/notion-spec-to-implementation/examples/database-migration.md b/skills/notion-spec-to-implementation/examples/database-migration.md new file mode 100644 index 00000000..32745fa1 --- /dev/null +++ b/skills/notion-spec-to-implementation/examples/database-migration.md @@ -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 diff --git a/skills/notion-spec-to-implementation/examples/ui-component.md b/skills/notion-spec-to-implementation/examples/ui-component.md new file mode 100644 index 00000000..76009421 --- /dev/null +++ b/skills/notion-spec-to-implementation/examples/ui-component.md @@ -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 diff --git a/skills/notion-spec-to-implementation/reference/milestone-summary-template.md b/skills/notion-spec-to-implementation/reference/milestone-summary-template.md new file mode 100644 index 00000000..807cbe21 --- /dev/null +++ b/skills/notion-spec-to-implementation/reference/milestone-summary-template.md @@ -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 +- Deliverable 1 +- [Link to PR/deployment] + +### Metrics +- [Relevant metric] +- [Relevant metric] + +### Learnings +- [What went well] +- [What to improve] + +### Next Phase +Starting [Phase name] on [Date] +``` + diff --git a/skills/notion-spec-to-implementation/reference/progress-tracking.md b/skills/notion-spec-to-implementation/reference/progress-tracking.md new file mode 100644 index 00000000..14b0061e --- /dev/null +++ b/skills/notion-spec-to-implementation/reference/progress-tracking.md @@ -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 +- Task 1 ✅ +- Task 2 ✅ +- Task 3 ✅ + +### 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] Database schema +- [x] API scaffolding +- [x] Auth setup + +### Phase 2: Core Features +- [x] User management +- [ ] Dashboard +- [ ] Reporting +``` + +### 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 + diff --git a/skills/notion-spec-to-implementation/reference/progress-update-template.md b/skills/notion-spec-to-implementation/reference/progress-update-template.md new file mode 100644 index 00000000..70a2f0bd --- /dev/null +++ b/skills/notion-spec-to-implementation/reference/progress-update-template.md @@ -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] +``` + diff --git a/skills/notion-spec-to-implementation/reference/quick-implementation-plan.md b/skills/notion-spec-to-implementation/reference/quick-implementation-plan.md new file mode 100644 index 00000000..be42908a --- /dev/null +++ b/skills/notion-spec-to-implementation/reference/quick-implementation-plan.md @@ -0,0 +1,26 @@ +# Quick Implementation Plan Template + +For simpler features or small changes. + +```markdown +# Implementation: [Feature Name] + +## Spec +Specification + +## Summary +[Quick description] + +## Tasks +- [ ] Task 1 +- [ ] Task 2 +- [ ] Task 3 + +## Timeline +Start: [Date] +Target completion: [Date] + +## Status +[Update as work progresses] +``` + diff --git a/skills/notion-spec-to-implementation/reference/spec-parsing.md b/skills/notion-spec-to-implementation/reference/spec-parsing.md new file mode 100644 index 00000000..e60a3cf0 --- /dev/null +++ b/skills/notion-spec-to-implementation/reference/spec-parsing.md @@ -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 + diff --git a/skills/notion-spec-to-implementation/reference/standard-implementation-plan.md b/skills/notion-spec-to-implementation/reference/standard-implementation-plan.md new file mode 100644 index 00000000..556a1d0b --- /dev/null +++ b/skills/notion-spec-to-implementation/reference/standard-implementation-plan.md @@ -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 +Original Specification + +## 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**: +- [ ] Database schema design +- [ ] API scaffolding +- [ ] Authentication setup + +**Deliverables**: Working API skeleton +**Estimated effort**: 3 days + +### Phase 2: Core Features (Week 2-3) +**Goal**: Implement main functionality + +**Tasks**: +- [ ] Feature A implementation +- [ ] Feature B implementation + +**Deliverables**: Core features working +**Estimated effort**: 1 week + +### Phase 3: Integration & Polish (Week 4) +**Goal**: Complete integration and refinement + +**Tasks**: +- [ ] Frontend integration +- [ ] Testing & QA + +**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 +- Design Doc +- API Spec + +### Related Work +- Related Feature + +## 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] +``` + diff --git a/skills/notion-spec-to-implementation/reference/task-creation-template.md b/skills/notion-spec-to-implementation/reference/task-creation-template.md new file mode 100644 index 00000000..be0b8695 --- /dev/null +++ b/skills/notion-spec-to-implementation/reference/task-creation-template.md @@ -0,0 +1,34 @@ +# Task Creation Template + +When creating tasks from spec. + +```markdown +# [Task Name] + +## Context +Part of implementation for Feature Spec + +Implementation plan: Implementation Plan + +## 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] +``` + diff --git a/skills/notion-spec-to-implementation/reference/task-creation.md b/skills/notion-spec-to-implementation/reference/task-creation.md new file mode 100644 index 00000000..dd74bd6a --- /dev/null +++ b/skills/notion-spec-to-implementation/reference/task-creation.md @@ -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 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 Feature Spec + +Part of Implementation Plan - 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 +- Prerequisite Task or None + +### Blocks +- Dependent Task 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 +