diff --git a/skills/jd-phrase-detector/LICENSE.txt b/skills/jd-phrase-detector/LICENSE.txt new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/skills/jd-phrase-detector/LICENSE.txt @@ -0,0 +1 @@ + diff --git a/skills/jd-phrase-detector/REFERENCE.md b/skills/jd-phrase-detector/REFERENCE.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/skills/jd-phrase-detector/REFERENCE.md @@ -0,0 +1 @@ + diff --git a/skills/jd-phrase-detector/SKILL.md b/skills/jd-phrase-detector/SKILL.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/skills/jd-phrase-detector/SKILL.md @@ -0,0 +1 @@ + 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 new file mode 100644 index 00000000..579fb33d --- /dev/null +++ b/skills/notion-spec-to-implementation/SKILL.md @@ -0,0 +1,219 @@ +--- +name: notion-spec-to-implementation +description: Turns product or tech specs into concrete Notion tasks that Claude code can implement. Breaks down spec pages into detailed implementation plans with clear tasks, acceptance criteria, and progress tracking to guide development from requirements to completion. +--- + +# Spec to Implementation + +Transforms specifications into actionable implementation plans with progress tracking. Fetches spec documents, extracts requirements, breaks down into tasks, and manages implementation workflow. + +## Quick Start + +When asked to implement a specification: + +1. **Find spec**: Use `Notion:notion-search` to locate specification page +2. **Fetch spec**: Use `Notion:notion-fetch` to read specification content +3. **Extract requirements**: Parse and structure requirements from spec +4. **Create plan**: Use `Notion:notion-create-pages` for implementation plan +5. **Find task database**: Use `Notion:notion-search` to locate tasks database +6. **Create tasks**: Use `Notion:notion-create-pages` for individual tasks in task database +7. **Track progress**: Use `Notion:notion-update-page` to log progress and update status + +## Implementation Workflow + +### Step 1: Find the specification + +``` +1. Search for spec: + - Use Notion:notion-search with spec name or topic + - Apply filters if needed (e.g., created_date_range, teamspace_id) + - Look for spec title or keyword matches + - If not found or ambiguous, ask user for spec URL/ID + +Example searches: +- "User Authentication spec" +- "Payment Integration specification" +- "Mobile App Redesign PRD" +``` + +### Step 2: Fetch and analyze specification + +``` +1. Fetch spec page: + - Use Notion:notion-fetch with spec URL/ID from search results + - Read full content including requirements, design, constraints + +2. Parse specification: + - Identify functional requirements + - Note non-functional requirements (performance, security, etc.) + - Extract acceptance criteria + - Identify dependencies and blockers +``` + +See [reference/spec-parsing.md](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 + +**Plan includes**: Overview → Linked Spec → Requirements Summary → Technical Approach → Implementation Phases (Goal, Tasks checklist, Estimated effort) → Dependencies → Risks & Mitigation → Timeline → Success Criteria + +See [reference/standard-implementation-plan.md](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 + +## Implementation Status Tracking + +**Plan Status**: Update with phase completion (✅ Complete, 🔄 In Progress %, ⏳ Not Started) and overall percentage +**Task Aggregation**: Query task database by plan ID to generate summary (complete, in progress, blocked, not started) + +## Handling Spec Changes + +**Detection**: Fetch updated spec → compare with plan → identify new requirements → assess impact +**Propagation**: Update plan → create new tasks → update affected tasks → add change note → notify via comments +**Change Log**: Track spec evolution with date, what changed, and impact + +## Common Patterns + +**Feature Flag**: Backend (behind flag) → Testing → Frontend (flagged) → Internal rollout → External rollout +**Database Migration**: Schema design → Migration script → Staging test → Production migration → Validation +**API Development**: API design → Backend implementation → Testing & docs → Client integration → Deployment + + +## Best Practices + +1. **Always link spec and implementation**: Maintain bidirectional references +2. **Break down into small tasks**: Each task should be completable in 1-2 days +3. **Extract clear acceptance criteria**: Know when "done" is done +4. **Identify dependencies early**: Note blockers in plan +5. **Update progress regularly**: Daily notes for active work +6. **Track changes**: Document spec updates and their impact +7. **Use checklists**: Visual progress indicators help everyone +8. **Link deliverables**: PRs, designs, docs should link back to tasks + +## Advanced Features + +For additional implementation patterns and techniques, see the reference files in [reference/](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 + diff --git a/skills/quantitative-resume-auditor/REFERENCE.md b/skills/quantitative-resume-auditor/REFERENCE.md new file mode 100644 index 00000000..47f69515 --- /dev/null +++ b/skills/quantitative-resume-auditor/REFERENCE.md @@ -0,0 +1,108 @@ + + +# Quantitative Resume Auditor — Reference + +This file defines the benchmarks, metric categories, and JD coverage framework +used during the audit. Claude loads it during benchmarking and gap analysis. + +--- + +## 1. Density Benchmark Levels + +These thresholds come from analysis of executive and leadership resumes across +education, business, healthcare, and technology. They are not a published +HR industry standard — treat them as a calibrated professional heuristic. + +| Level | Score | What It Looks Like | Practical Risk | +|-------|-------|--------------------|----------------| +| Qualitative | below 1.5 | Bullet points describe duties, not results. Few or no numbers. | Likely screened out before a human reads it. | +| Competitive | 1.5 to 2.9 | Some metrics present — budgets, team sizes, rates. Results are there but not consistent. | Gets past screening but may not stand out in a competitive pool. | +| Gold Standard | 3.0 and above | Multiple metrics per bullet covering result, scale, and context. | Credible on paper. Interviewers can build questions directly from the data. | + +--- + +## 2. Metric Categories + +Count each category separately so the M total can be checked independently. + +| Category | What to Count | Examples | +|----------|--------------|----------| +| Percentages | Gains, rates, lifts, completion rates, reductions | "Increased proficiency by 25%", "35% efficiency lift" | +| Currency / Financial | Budgets, grants, revenue, cost savings, funding | "$8M grant", "reduced costs by $400K" | +| Headcount / Scale | People trained, students served, sites managed, partners | "Trained 5,000 educators", "supervised 15 staff" | +| Years / Time | Years of experience, program durations, project timelines | "25 years", "3-year program", "launched in 2019" | +| Score Gains | Test score improvements, rating increases, rankings | "+12 points on state assessment" | +| Efficiency | Processing time reductions, speed improvements | "35% reduction in data processing time" | +| Volume / Output | Publications, certifications, projects, transactions | "47 publications", "230 certified" | +| Ratio / Rates | Compliance, engagement, satisfaction, accuracy | "100% compliance", "95% completion rate" | + +--- + +## 3. The Impact Formula + +A well-written accomplishment bullet follows this structure: + + [Action verb] + [Quantified result] + [Scale or context] + [Method or tool] + +Example: Led a cross-functional team of 50 to grow annual revenue by 22% ($4M) +across 12 international sites by redesigning the incentive structure. + +That one bullet contains four metrics: 50 people, 22%, $4M, 12 sites. + +Rule of thumb: A bullet with no metrics is a duty statement, not an +accomplishment statement. Ask the user: How much? How many? Over what time? +With what budget? + +--- + +## 4. JD Coverage Framework + +When a job description is provided, map resume evidence to these domains. +Adjust the domain names to match the specific JD language. + +| Domain | Resume Evidence to Look For | +|--------|-----------------------------| +| Academic / Program Outcomes | Proficiency gains, mastery rates, completion rates, grade improvements | +| Operational Leadership | Efficiency gains, cost reductions, compliance rates, project timelines | +| People Leadership | Staff supervised, capacity built, retention rates, training delivered | +| Governance / Authorization | Policies adopted, compliance rates, board reporting, funding managed | +| Community / Culture | Partnerships established, stakeholder engagement, participation rates | +| Funding / Resources | Dollars secured or managed, grants won, ROI demonstrated | +| Research / Innovation | Publications, programs founded, frameworks designed, awards received | + +Scoring: Count how many JD requirements have at least one quantified bullet +as evidence. Coverage % = evidenced requirements / total requirements x 100. + +--- + +## 5. Gap Risk Classification + +Use this table when flagging uncovered JD requirements. + +| Risk Level | Meaning | Where to Address It | +|------------|---------|---------------------| +| High | A stated core responsibility with no evidence in the resume | Prepare a specific quantified story for the interview | +| Medium | Partially evidenced, or can be inferred from nearby bullets | Cover letter or leadership statement | +| Low | Soft skills, cultural fit, or location-specific requirements | Verbal in the interview | + +--- + +## 6. Score Interpretation Notes + +Density above 5.0 — Common in academic CVs and research-heavy resumes. +Appropriate for scientific roles. For general leadership positions, consider +whether the density is helping or overwhelming the reader. + +Quantification rate above 100% — This is a calculation artifact. One bullet +can contain six metrics but is only counted once in Q. The script caps this at 100%. + +Short resumes with fewer than 15 bullets — Density scores are more volatile +with small B values. Note the limited sample size in the report. + +Career stage context: +- Early career: 1.0 to 2.0 (fewer measurable outcomes is normal) +- Mid-career: 2.0 to 3.5 +- Executive or senior leadership: 3.0 to 6.0 and above diff --git a/skills/quantitative-resume-auditor/SKILL.md b/skills/quantitative-resume-auditor/SKILL.md new file mode 100644 index 00000000..cac22334 --- /dev/null +++ b/skills/quantitative-resume-auditor/SKILL.md @@ -0,0 +1,387 @@ + + +--- +name: quantitative-resume-auditor +description: Audits resumes with Python: metric density (M/B ratio) vs. 3.0 Gold Standard. With a JD: token coverage, knockout flags, False-Miss audit. Triggers on resume audit, density check, or JD gap analysis. +--- + +# Quantitative Resume Auditor + +**Author:** Dr. Fabiano de Souza + +This skill turns a resume review from a subjective opinion into a calculated score. +It counts every numeric data point, runs Python to compute a Metric Density ratio, +and tells the user exactly which bullets are pulling the score down. + +**Formula:** `Density = Total Numeric Metrics (M) / Total Bullet Points (B)` + +A score of 3.0 or above is the target. The skill works on any resume regardless of +length, profession, or career stage. All counts are dynamic — no fixed target number. + +When a job description is also provided, the skill runs a second pass: JD token +coverage, knockout flag check, and a False-Miss Audit that distinguishes real gaps +from synonym differences. + +See `REFERENCE.md` for benchmark definitions, metric categories, and JD coverage framework. + +--- + +## Instructions for Claude + +### Step 1 — Data Extraction + +Read the full resume and count these three variables. Do not estimate. + +| Variable | Definition | +|----------|------------| +| B | Total bullet points (every accomplishment statement) | +| M | Total numeric metrics (every number, %, $, ratio, or time reference) | +| Q | Bullets that contain at least one metric | + +List the M count broken down by category so the total is verifiable: +- Percentages (gains, rates, lifts, completion %) +- Currency (budgets, grants, revenue, cost savings) +- Headcount / scale (people, students, sites, partners) +- Years / time (years of experience, program durations, dates) +- Score gains (test score improvements, rating increases) +- Efficiency (time saved, processing reductions, cycle improvements) +- Volume / output (publications, certifications, projects, transactions) + +### Step 2 — Python Computation + +Run the following code using Claude's code execution tool. +Do not do this math in plain text. + +```python +import re + +def tokenize(text): + """Lowercase, strip punctuation, return content words (4+ chars).""" + words = re.findall(r'\b[a-zA-Z]{4,}\b', text.lower()) + # Remove common stopwords that add noise to coverage + stopwords = { + 'that', 'with', 'this', 'from', 'have', 'been', 'will', 'their', + 'they', 'what', 'when', 'your', 'which', 'also', 'into', 'more', + 'about', 'than', 'were', 'each', 'such', 'over', 'other', 'these' + } + return [w for w in words if w not in stopwords] + + +def run_resume_audit(M, B, Q, resume_text="", jd_text=""): + """ + Core audit function. + M, B, Q — counts Claude extracted manually in Step 1. + resume_text, jd_text — full plain text of each document (optional). + When both texts are provided, JD coverage and gap analysis run automatically. + """ + if B == 0: + return {"Error": "No bullet points found. Please provide a resume."} + + density = round(M / B, 2) + # Cap at 100% — a bullet with multiple metrics still counts as one quantified bullet + rate = min(round((Q / B) * 100, 1), 100.0) + + if density >= 3.0: + status = "GOLD STANDARD" + rec = "Density is strong. Shift focus to job description coverage gaps." + elif density >= 1.5: + status = "COMPETITIVE" + rec = "Find the five weakest bullets and add one or two metrics to each." + else: + status = "QUALITATIVE" + rec = "Rewrite responsibility statements as accomplishment statements." + + result = { + "Total Metrics (M)": M, + "Bullet Points (B)": B, + "Quantified Bullets (Q)": Q, + "Density Score": f"{density} metrics/bullet", + "Quantification Rate": f"{rate}%", + "Status": status, + "Recommendation": rec + } + + # --- JD pass: only runs when both texts are supplied --- + if resume_text and jd_text: + resume_tokens = set(tokenize(resume_text)) + jd_tokens = set(tokenize(jd_text)) + + if jd_tokens: + covered = jd_tokens & resume_tokens + missing = jd_tokens - resume_tokens + coverage = round(len(covered) / len(jd_tokens) * 100, 1) + + # Coverage interpretation — heuristic bands, not published benchmarks + if coverage >= 35: + cov_note = "Strong vocabulary alignment with JD." + elif coverage >= 20: + cov_note = "Moderate alignment. Review missing terms below." + else: + cov_note = "Low alignment. Resume may not match recruiter search terms." + + result["JD Token Coverage"] = f"{coverage}% ({len(covered)}/{len(jd_tokens)} JD terms)" + result["Coverage Note"] = cov_note + result["Potentially Missing"] = sorted(missing)[:20] # top 20 for review + + return result + + +# Replace these values with actual counts and text from the documents +M = 0 # total numeric metrics counted +B = 0 # total bullet points counted +Q = 0 # bullets containing at least one metric +resume_text = "" # paste full resume text here +jd_text = "" # paste full JD text here (leave empty if no JD) + +result = run_resume_audit(M, B, Q, resume_text, jd_text) +for k, v in result.items(): + if isinstance(v, list): + print(f"{k}:") + for item in v: + print(f" - {item}") + else: + print(f"{k}: {v}") +``` + +### Step 3 — Report Format + +Deliver three sections: + +**1. Audit Scoreboard** +A table with M, B, Q, Density Score, Quantification Rate, and Status. + +**2. Category Breakdown** +List the count per category so the M total is independently verifiable. +Example: `Percentages: 34 | Currency: 5 | Headcount: 8 | Years: 30` + +**3. Gap Analysis** + +*If a job description is provided*, run three checks in order: + +**A. Knockout Flag** +Before any overlap analysis, scan the JD for hard requirements — mandatory +certifications, licenses, degree requirements, or lines using "must have," +"required," or "minimum." For each one, check whether the resume provides +direct evidence. Flag any that are missing as HIGH RISK — these are the +SPDX-License-Identifier: Apache-2.0 +Copyright 2026 Dr. Fabiano de Souza +--> + +--- +name: quantitative-resume-auditor +description: Audits resumes with Python: metric density (M/B ratio) vs. 3.0 Gold Standard. With a JD: token coverage, knockout flags, False-Miss audit. Triggers on resume audit, density check, or JD gap analysis. +--- + +# Quantitative Resume Auditor + +**Author:** Dr. Fabiano de Souza + +This skill turns a resume review from a subjective opinion into a calculated score. +It counts every numeric data point, runs Python to compute a Metric Density ratio, +and tells the user exactly which bullets are pulling the score down. + +**Formula:** `Density = Total Numeric Metrics (M) / Total Bullet Points (B)` + +A score of 3.0 or above is the target. The skill works on any resume regardless of +length, profession, or career stage. All counts are dynamic — no fixed target number. + +When a job description is also provided, the skill runs a second pass: JD token +coverage, knockout flag check, and a False-Miss Audit that distinguishes real gaps +from synonym differences. + +See `REFERENCE.md` for benchmark definitions, metric categories, and JD coverage framework. + +--- + +## Instructions for Claude + +### Step 1 — Data Extraction + +Read the full resume and count these three variables. Do not estimate. + +| Variable | Definition | +|----------|------------| +| B | Total bullet points (every accomplishment statement) | +| M | Total numeric metrics (every number, %, $, ratio, or time reference) | +| Q | Bullets that contain at least one metric | + +List the M count broken down by category so the total is verifiable: +- Percentages (gains, rates, lifts, completion %) +- Currency (budgets, grants, revenue, cost savings) +- Headcount / scale (people, students, sites, partners) +- Years / time (years of experience, program durations, dates) +- Score gains (test score improvements, rating increases) +- Efficiency (time saved, processing reductions, cycle improvements) +- Volume / output (publications, certifications, projects, transactions) + +### Step 2 — Python Computation + +Run the following code using Claude's code execution tool. +Do not do this math in plain text. + +```python +import re + +def tokenize(text): + """Lowercase, strip punctuation, return content words (4+ chars).""" + words = re.findall(r'\b[a-zA-Z]{4,}\b', text.lower()) + stopwords = { + 'that', 'with', 'this', 'from', 'have', 'been', 'will', 'their', + 'they', 'what', 'when', 'your', 'which', 'also', 'into', 'more', + 'about', 'than', 'were', 'each', 'such', 'over', 'other', 'these' + } + return [w for w in words if w not in stopwords] + + +def run_resume_audit(M, B, Q, resume_text="", jd_text=""): + if B == 0: + return {"Error": "No bullet points found. Please provide a resume."} + + density = round(M / B, 2) + rate = min(round((Q / B) * 100, 1), 100.0) + + if density >= 3.0: + status = "GOLD STANDARD" + rec = "Density is strong. Shift focus to job description coverage gaps." + elif density >= 1.5: + status = "COMPETITIVE" + rec = "Find the five weakest bullets and add one or two metrics to each." + else: + status = "QUALITATIVE" + rec = "Rewrite responsibility statements as accomplishment statements." + + result = { + "Total Metrics (M)": M, + "Bullet Points (B)": B, + "Quantified Bullets (Q)": Q, + "Density Score": f"{density} metrics/bullet", + "Quantification Rate": f"{rate}%", + "Status": status, + "Recommendation": rec + } + + if resume_text and jd_text: + resume_tokens = set(tokenize(resume_text)) + jd_tokens = set(tokenize(jd_text)) + + if jd_tokens: + covered = jd_tokens & resume_tokens + missing = jd_tokens - resume_tokens + coverage = round(len(covered) / len(jd_tokens) * 100, 1) + + if coverage >= 35: + cov_note = "Strong vocabulary alignment with JD." + elif coverage >= 20: + cov_note = "Moderate alignment. Review missing terms below." + else: + cov_note = "Low alignment. Resume may not match recruiter search terms." + + result["JD Token Coverage"] = f"{coverage}% ({len(covered)}/{len(jd_tokens)} JD terms)" + result["Coverage Note"] = cov_note + result["Potentially Missing"] = sorted(missing)[:20] + + return result + + +M = 0 +B = 0 +Q = 0 +resume_text = "" +jd_text = "" + +result = run_resume_audit(M, B, Q, resume_text, jd_text) +for k, v in result.items(): + if isinstance(v, list): + print(f"{k}:") + for item in v: + print(f" - {item}") + else: + print(f"{k}: {v}") +``` + +### Step 3 — Report Format + +Deliver three sections: + +**1. Audit Scoreboard** +A table with M, B, Q, Density Score, Quantification Rate, and Status. + +**2. Category Breakdown** +List the count per category so the M total is independently verifiable. +Example: `Percentages: 34 | Currency: 5 | Headcount: 8 | Years: 30` + +**3. Gap Analysis** + +*If a job description is provided*, run three checks in order: + +**A. Knockout Flag** +Scan the JD for hard requirements — mandatory certifications, licenses, +degree requirements, or lines using "must have," "required," or "minimum." +For each one, check whether the resume provides direct evidence. Flag any +that are missing as HIGH RISK — these are the documented auto-filter +triggers, more consequential than any keyword score. +Example: "Valid teaching license — not evidenced in resume." + +**B. JD Token Coverage** +Report the coverage % from the Python output. For each term in +"Potentially Missing," apply a False-Miss Audit before calling it a real gap: +- Covered by a synonym? (e.g., "AI" covers "artificial") +- Morphological variant present? (e.g., "communicated" covers "communicate") +- Inferrable title or role equivalent? +Mark SYNONYM/COVERED if yes. Only flag as a real gap if genuinely absent. + +**C. Coverage Map** +Map each JD responsibility area to resume bullets with quantified evidence. +Flag uncovered items by risk level (see `REFERENCE.md` Section 5): +High / Medium / Low. + +*If no job description is provided:* list the three to five bullets with the +lowest metric count and suggest what specific data the user could add. + +--- + +## When to Use This Skill + +Trigger when the user: + +- Uploads a resume and asks for an audit, score, or density check +- Asks "Is my resume quantitative enough?" or similar +- Asks whether their resume matches a job description +- Requests a JD gap analysis or coverage map +- Wants to benchmark their resume before applying for a role + +--- + +## Example Prompts + +``` +"Audit this resume for data density." +"Score my resume against the 3.0 benchmark." +"Run a gap analysis — here is my resume and the job description." +"Which bullets are weakest and what numbers should I add?" +"Do I meet the hard requirements in this job posting?" +``` + +--- + +## Notes + +- **Dynamic counts.** The skill counts whatever is in the document. + There is no minimum or maximum target — density scales with the resume. +- **Code execution required.** Enable it in Claude settings before using this skill. +- **The 3.0 benchmark is a professional heuristic**, not a published HR standard. + It was developed through analysis of executive and leadership resumes. + See `REFERENCE.md` for full definitions. +- **JD token coverage thresholds are heuristics**, not externally validated benchmarks. + Use them to compare one draft against another, not as absolute pass/fail scores. + Modern ATS platforms (Workday, Greenhouse, Lever) use semantic matching and + ontology graphs — not literal keyword counts — to rank candidates. +- **Knockout flags take priority** over all overlap metrics. A missing required + certification eliminates a candidate regardless of coverage score. +- **False-Miss Audit prevents over-editing.** Do not add a term to the resume + if the concept is already covered by a synonym or equivalent phrase. +- **Works across professions** — education, business, healthcare, technology, + government, and nonprofit roles all use quantifiable accomplishments. diff --git a/skills/resume-summary-auditor/LICENSE.txt b/skills/resume-summary-auditor/LICENSE.txt new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/skills/resume-summary-auditor/LICENSE.txt @@ -0,0 +1 @@ + diff --git a/skills/resume-summary-auditor/REFERENCE.md b/skills/resume-summary-auditor/REFERENCE.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/skills/resume-summary-auditor/REFERENCE.md @@ -0,0 +1 @@ + diff --git a/skills/resume-summary-auditor/SKILL.md b/skills/resume-summary-auditor/SKILL.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/skills/resume-summary-auditor/SKILL.md @@ -0,0 +1 @@ +