implementation-plan
Break the change into ordered, reviewable steps with checkpoints, so a long task can be stopped and resumed. Use when breaking changes into ordered, testable steps with checkpoints.
- License 许可
- MIT
- 最近更新
- 2026-10-02
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- implementation-plan
- group
- Plan
- description
- Break the change into ordered, reviewable steps with checkpoints, so a long task can be stopped and resumed. Use when breaking changes into ordered, testable steps with checkpoints.
- last_reviewed
- 1788652800000
02 资源文件 2
- 参考文档evals/routing.yaml880 B
- 其他implementation-plan.skill3.1 KB
03 SKILL.md 正文
implementation-plan
Core Philosophy
Diving directly into code on complex architectural refactors without a written implementation plan leads to broken builds, forgotten edge cases, scope creep, and irreversible git wreckage. An implementation plan is an engineering blueprint. It breaks complex tasks into ordered, bite-sized increments with testable verification checkpoints at each step—ensuring that long-running work can be stopped, reviewed, and resumed at any time with complete confidence.
4-Step Implementation Planning Discipline
Step 1: Scope, Architecture & Dependency Ordering
- Dependency Inversion Ordering:
- Order components logically so that dependencies are created before dependents:
-
- Core Data Models / Database Schema Migrations.
-
- Internal Services / Business Logic.
-
- API Endpoints / Controllers.
-
- Frontend UI / Consumer Integration.
-
- Order components logically so that dependencies are created before dependents:
- Explicit Non-Goals:
- Clearly delineate what will not be built in this iteration to prevent scope creep.
Step 2: Atomic Phase Breakdown & Checkpoint Design
- The 30-Minute Task Rule:
- Break work down into discrete tasks that take $\le 30$ minutes to implement and verify.
- Verification Checkpoints:
- Every single task must have an explicit verification step:
- "Run
npm test src/auth.test.ts-> Expect 4 passing tests." - "Run
curl -I http://localhost:3000/api/health-> Expect 200 OK."
- "Run
- Every single task must have an explicit verification step:
Step 3: TDD Integration & Regression Defense
- Test-First Stance:
- Specify the automated test files to be written before the implementation code is touched.
- Define expected failure conditions (red) and passing criteria (green).
Step 4: Rollback & Risk Mitigation Protocol
- De-risking Breaking Changes:
- Use the Expand and Contract (Parallel Run) pattern for schema and API changes:
- Phase 1 (Expand): Add new field/endpoint; support both old and new.
- Phase 2 (Migrate): Shift traffic to new field/endpoint.
- Phase 3 (Contract): Deprecate and remove old field/endpoint.
- Use the Expand and Contract (Parallel Run) pattern for schema and API changes:
Deliverable Format: Implementation Plan Template (IMPLEMENTATION-PLAN.md)
# Implementation Plan: [Feature / Refactor Name]
## 1. Overview & Architectural Goal
[1-2 paragraphs explaining what the change accomplishes and the architectural rationale.]
## 2. Open Questions & Design Decisions
- [Decision A]: Chosen approach and rationale.
- [Question B]: Awaiting team clarification.
## 3. Ordered Implementation Phases
### Phase 1: Database & Data Model Layer
- [ ] **Task 1.1**: Create migration adding `organization_id` column to `users` table.
- *Files*: `prisma/migrations/20260906_add_org_id.sql`
- *Verification*: Run `npx prisma migrate dev` and verify column exists via `psql`.
- [ ] **Task 1.2**: Update Prisma schema and generate client.
- *Files*: `prisma/schema.prisma`
- *Verification*: Run `npx prisma generate` -> builds clean.
### Phase 2: Core Domain Logic & Unit Tests
- [ ] **Task 2.1 [TDD]**: Write unit tests for OrgMembershipService.
- *Files*: `tests/unit/org-service.test.ts`
- *Verification*: Run `npm test tests/unit/org-service.test.ts` -> Fails (Red).
- [ ] **Task 2.2**: Implement OrgMembershipService methods.
- *Files*: `src/services/OrgMembershipService.ts`
- *Verification*: Run `npm test tests/unit/org-service.test.ts` -> Passes (Green).
### Phase 3: API Endpoints & Route Handlers
- [ ] **Task 3.1**: Expose `POST /api/v1/organizations/:id/members`.
- *Verification*: Execute curl test script against local test server.
## 4. Verification Plan
- **Automated Tests**: `npm run test:all`
- **Lint & Types**: `npm run lint && npm run typecheck`
- **Manual Verification**: End-to-end user invitation flow in local staging browser.
Worked Example: Zero-Downtime Database Migration Plan
- Refactor: Split single
User.namecolumn intoUser.firstNameandUser.lastName. - Phases:
- Phase 1: Added nullable columns
firstNameandlastName. - Phase 2: Dual-write to both
nameand new columns in application code. - Phase 3: Background script backfilled historical rows.
- Phase 4: Switched reads to
firstName/lastName. - Phase 5: Dropped legacy
namecolumn.
- Phase 1: Added nullable columns
- Outcome: 100% zero downtime across 5M production records.
Verification Checklist
- [ ] Tasks are arranged in logical dependency order (data -> logic -> API -> UI).
- [ ] Every individual task includes exact file paths and a verifiable test command.
- [ ] Explicit non-goals are defined to restrict scope.
- [ ] TDD unit tests are scheduled prior to implementation tasks.
- [ ] Rollback strategy is documented for database or API changes.
Anti-Patterns
- The Monolithic Step: Writing "Step 1: Build the backend" (too vague, impossible to verify incrementally).
- Skipping Checkpoints: Writing 2,000 lines of code across 15 files before running a single test.
- Unverified Assumptions: Proceeding with execution while major architectural questions remain unresolved.
04 同仓库更多 Skills
workflow-optimizer
Moved to workflow-mapping in skills-agents. Removed in v4.1.
webhooks
Build webhook receivers with signature verification, idempotency, retries and dead letter queues. Use when implementing, verifying, or signing incoming/outgoing webhooks.
webhook-handler-builder
Moved to webhooks in skills-developer. Removed in v4.1.
voice-ai-integration-engineer
Moved to speech-pipelines in skills-developer. Removed in v4.1.
typescript-migrator
Moved to port-code in skills-developer. Removed in v4.1.
trigger-dev
Moved to trigger-dev in skills-agents. Removed in v4.1.