Agent skill
implementation-planning
Use when you have a design or requirements for a multi-step task, before writing code. Creates bite-sized TDD task plans with exact file paths, complete code, and verification steps.
Install this agent skill to your Project
npx add-skill https://github.com/jagreehal/jagreehal-claude-skills/tree/main/skills/implementation-planning
SKILL.md
Implementation Planning
Write comprehensive implementation plans assuming the executor has zero context. Document everything: which files to touch, complete code, how to test. Bite-sized tasks. DRY. YAGNI. TDD.
The Iron Law
NO IMPLEMENTATION WITHOUT A PLAN FIRST
For multi-step tasks, write the plan before writing code.
When to Use
- MUST: Before implementing features with 3+ steps
- MUST: Before complex refactoring
- SHOULD: When multiple files need coordinated changes
- MAY: Skip for single-file, single-function changes
Bite-Sized Task Granularity
Each step is ONE action (2-5 minutes):
1. Write the failing test - step
2. Run it to verify it fails - step
3. Implement minimal code to pass - step
4. Run tests to verify they pass - step
5. Commit - step
Plan Structure
Header (Required)
# [Feature Name] Implementation Plan
**Goal:** [One sentence describing what this builds]
**Architecture:** [2-3 sentences about approach]
**Tech Stack:** [Key technologies/libraries]
---
Task Structure
### Task N: [Component Name]
**Files:**
- Create: `exact/path/to/file.ts`
- Modify: `exact/path/to/existing.ts:123-145`
- Test: `tests/exact/path/to/test.ts`
**Step 1: Write the failing test**
\`\`\`typescript
import { describe, it, expect } from 'vitest';
import { mock } from 'vitest-mock-extended';
import { getUser, type GetUserDeps } from './get-user';
describe('getUser', () => {
it('returns NOT_FOUND when user does not exist', async () => {
const deps = mock<GetUserDeps>();
deps.db.findUser.mockResolvedValue(null);
const result = await getUser({ userId: '123' }, deps);
expect(result.ok).toBe(false);
if (!result.ok) {
expect(result.error).toBe('NOT_FOUND');
}
});
});
\`\`\`
**Step 2: Run test to verify it fails**
Run: `npm test src/domain/get-user.test.ts`
Expected: FAIL with "Cannot find module './get-user'"
**Step 3: Write minimal implementation**
\`\`\`typescript
import { err, type Result } from '@/result';
export type GetUserDeps = {
db: { findUser: (id: string) => Promise<User | null> };
};
export async function getUser(
args: { userId: string },
deps: GetUserDeps
): Promise<Result<User, 'NOT_FOUND'>> {
return err('NOT_FOUND');
}
\`\`\`
**Step 4: Run test to verify it passes**
Run: `npm test src/domain/get-user.test.ts`
Expected: PASS
**Step 5: Commit**
\`\`\`bash
git add src/domain/get-user.ts src/domain/get-user.test.ts
git commit -m "feat(user): add getUser with NOT_FOUND handling"
\`\`\`
MUST/SHOULD/NEVER Rules
MUST
- MUST: Include exact file paths (never "in the appropriate file")
- MUST: Include complete code (never "add validation logic")
- MUST: Include exact commands with expected output
- MUST: Follow TDD cycle (test → fail → implement → pass → commit)
- MUST: Save plans to
docs/plans/YYYY-MM-DD-<feature-name>.md
SHOULD
- SHOULD: Use fn(args, deps) pattern for new functions
- SHOULD: Use Result types for error handling
- SHOULD: Include type definitions in implementation
- SHOULD: Reference line numbers for modifications
NEVER
- NEVER: Write vague steps ("add appropriate error handling")
- NEVER: Skip the verification steps
- NEVER: Bundle multiple changes in one step
- NEVER: Assume executor knows the codebase
Plan Quality Checklist
Before finalizing:
- Every step is one action (2-5 minutes)
- All file paths are exact
- All code is complete and copy-pasteable
- All commands include expected output
- TDD cycle is clear for each task
- Commit messages follow project conventions
Execution Handoff
After saving the plan:
Plan complete and saved to `docs/plans/<filename>.md`.
Ready to execute? I'll follow TDD workflow for each task.
Integration
| Skill | Relationship |
|---|---|
design-exploration |
Design must be approved before planning |
tdd-workflow |
Tasks follow strict TDD cycle |
fn-args-deps |
New functions use fn(args, deps) pattern |
result-types |
Error handling uses Result types |
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
jagreehal/jagreehal-claude-skills
skill-authoring
Use when creating, editing, or reviewing skills. Covers discovery optimization, structure patterns, testing approaches, and format decisions.
jagreehal/jagreehal-claude-skills
testing-strategy
Test pyramid approach with unit, integration, and load tests. DI enables testability. Use vitest-mock-extended for typed mocks.
jagreehal/jagreehal-claude-skills
api-design
Build production-ready HTTP APIs with clean handlers, consistent error envelopes, health checks, CORS, and operational excellence.
jagreehal/jagreehal-claude-skills
validation-boundary
Validate at the boundary with Zod schemas and branded types. Business functions trust validated input.
jagreehal/jagreehal-claude-skills
branch-completion
Use when implementation is complete and tests pass. Guides completion by presenting structured options for merge, PR, or cleanup.
jagreehal/jagreehal-claude-skills
resilience
Add retry, timeout, and circuit breaker patterns at the workflow level. Business functions stay clean.
Didn't find tool you were looking for?