implementation-plan-best-practices
Educational guide on best practices for creating implementation plans that prevent drift. Covers style anchors, task sizing, TDD requirements, affirmative instructions, drift handling, and quality gates. Use when creating or improving implementation plans to ensure they follow proven patterns.
How do I install this agent skill?
npx skills add https://github.com/validkeys/sherpy --skill implementation-plan-best-practicesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a set of educational best practices and templates for creating implementation plans. It focuses on preventing architectural drift and ensuring code quality through testing and specific constraints. No security risks were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
2/4 files flagged
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
Implementation Plan Best Practices
Proven best practices for creating implementation plans that prevent drift and maintain alignment with project standards.
Core Principle
Models optimize locally; enforce global constraints with layered verification (prompt → IDE → commit → CI → runtime).
1. Style Anchors
- Always include 2-3 exemplary files as templates in prompts
- Reference exact paths and line numbers (e.g.,
src/auth/login.ts:45-78) - Prefer concrete repository examples with code + tests + README
- Example:
examples/style-anchor/pkg/greeter/greeter.go(code),greeter_test.go(tests),README.md(docs) - Place anchors early in task instructions to prevent architectural drift
Template:
Style Anchors:
- src/auth/login.ts:45-78 (authentication pattern with proper error handling)
- src/auth/login.test.ts:12-34 (test structure for auth flows)
- src/middleware/validation.ts:15-30 (input validation pattern)
2. Task Sizing
- Target duration: 30-150 minutes (0.5-2.5 hours)
- File scope: 1-3 files per task (max 5 with justification)
- Splitting strategy: tests + scaffolding → minimal implementation → refactor & polish
- Commit after each small task; revert immediately on drift
- If task <30m, document rationale or split it
Examples:
- Small: Fix bug in
src/utils/parse.ts— 30-60 mins - Medium: Add API endpoint
src/server/user.tswith tests — 90-150 mins - Large: Migrate auth system — Split into design + 3-5 incremental tasks
3. Affirmative Instructions
- State permitted actions explicitly (e.g.,
ONLY use: cobra, go-playground/validator, sqlite) - Avoid negative framing ("Don't use X" → "ONLY use: Y, Z")
- Specify exact file scopes:
Touch ONLY: src/api/handlers/user.ts, user.test.ts
4. Tiered Rules
- Global: User prefs (format, language, length)
- Project: Persistent rules in
CLAUDE.mdor.cursor/rules/(loaded every session) - Context-aware: Auto-attached rules per directory or file pattern
5. TDD as Anchor
- Require TDD checklist: tests → minimal code → more tests → refactor
- When tests fail: "Revise implementation to pass this test while keeping all previously passing tests. Do not modify the test. Do not add dependencies."
- Include explicit validation commands:
npm test src/auth/login.test.ts
go test ./pkg/auth -v
pytest tests/test_auth.py -v
6. Prompt Positioning
- Put critical specs, style anchors, and hard rules at the beginning
- Reiterate them at the end of prompts
- Avoid burying requirements in the middle
7. Model Strategies
- Claude: Use for surgical, minimal-diff edits; request
research → plan → implement,minimal diff, no renames, explain each edit; use thinking triggers (think,think hard,ultrathink) - GPT: Use for exploratory/greenfield work and code review; ask for tactical plans and side-effect checks
8. Self-Consistency & AI-on-AI Review
- Generate 3+ implementations (higher temperature), then ask model to pick most consistent
- Use multi-model review (e.g., Claude writes, GPT/Gemini reviews) to catch subtle issues
9. Drift Handling
Stop & revert immediately if:
- New dependencies introduced (not in allowed list)
- Files touched outside specified targets (>3 unexpected files)
- Linting/type errors cannot be resolved within task scope
- Tests fail and model proposes changing tests instead of implementation
Immediate actions:
- Stop the session
- Revert to pre-task state (only if changes produced by agent in this session)
- Create incident note in
docs/drift-incidents/with:- What happened
- Files changed unexpectedly
- New dependencies proposed
- Remediation steps
Allowed deviations:
- Minor formatting (editorconfig)
- Whitespace-only edits
- Single-line refactors within scope and type-checked
Recording learnings:
- Update
.cursor/rules/orCLAUDE.mdwith new rules after each session - Add to style anchors if new pattern discovered
10. Quality Gates
Pre-commit:
make lintwith zero warningsmake testwith all tests passingmake typecheckwith zero errors
CI gates:
- Count violations (gofmt, lint, typecheck) and fail if threshold exceeded
- Run tests with race detection (e.g.,
go test -race)
Per-task validation:
validation:
commands:
- npm run lint
- npm test src/[module].test.ts
- npm run typecheck
expected_output: "All tests passing, 0 lint errors"
failure_handling: "STOP and report. Do not continue to next task."
11. Layered Verification
- Prompt level: Explicit constraints, style anchors, task sizing
- IDE level: Linting, type checking, auto-formatting
- Commit level: Pre-commit hooks, validation scripts
- CI level: Quality gates, test suites, coverage thresholds
- Runtime level: Input validation, proper error handling, monitoring
12. Key Learnings from Milestone 0
- Make templates explicit vs concrete: Include all schema-required top-level fields to avoid validation failures
- Enforce concrete style anchors early: Include 2-3 concrete anchors (code + tests + README) on every planning task
- Mark inferred edits: Use
assumption: truewith rationale for any inferred additions - Respect task-sizing constraints: Enforce 30-150m task estimates; split shorter tasks with rationale
- Keep validation inline: Add
validationsummary withquality_score,issues, andapproval - Prefer concrete execution snippets: Add explicit validator commands in
instructions - Scope implementation rules: Keep implementation-only pattern checks scoped with
when: implementation_phase - Use repository examples as anchors: Small, well-scoped examples are high-leverage anchors
Task Template Example
task:
id: t-auth-001
name: "Add login endpoint with JWT validation"
estimate_minutes: 90
files:
touch_only: [src/api/handlers/auth.ts, src/api/handlers/auth.test.ts]
modify_only: [src/api/routes.ts]
style_anchors:
- {path: src/api/handlers/user.ts, lines: 45-78, pattern: "Handler with proper error handling"}
- {path: src/api/handlers/user.test.ts, lines: 12-45, pattern: "Test structure for API handlers"}
constraints:
dependencies:
only_use: [jsonwebtoken, express-validator]
file_scope:
max_files: 3
stop_if_exceeded: true
instructions: |
## CRITICAL CONSTRAINTS
- ONLY modify files listed above
- ONLY use dependencies: jsonwebtoken, express-validator
- MUST pass: npm test, npm run lint
## Style Anchors
See src/api/handlers/user.ts:45-78 for handler pattern
See src/api/handlers/user.test.ts:12-45 for test structure
## TDD Checklist
- [ ] Write failing test for POST /auth/login
- [ ] Implement minimal handler to pass
- [ ] Add tests for edge cases
- [ ] Refactor for clarity
## Drift Policy
STOP if: files touched >3, new dependencies, tests fail
## Validation
npm test src/api/handlers/auth.test.ts && npm run lint && npm run typecheck
validation:
commands: [npm test src/api/handlers/auth.test.ts, npm run lint, npm run typecheck]
expected_output: "All tests passing, 0 errors"
failure_handling: "STOP. Revise implementation to pass tests."
Quick Practical Checklist
When creating implementation plans:
- Create
CLAUDE.mdor.cursor/rules/with prompt-level rules - Add 2-3 concrete style anchors to prompts (prefer repository examples)
- Rescope tasks to 30m-2.5h and commit per task
- Convert negative constraints to affirmative instructions
- Enforce linting zero-warnings, pre-commit hooks, and CI gates
- Require TDD plans and tests before making changes
- Use proper error handling for runtime validation
- Include all schema-required fields in generated YAML
- Mark inferred additions with
assumption: trueand rationale - Place critical constraints at beginning AND end of prompts
Common Anti-Patterns
| Anti-Pattern | Problem | Fix |
|---|---|---|
| No style anchors | Model introduces inconsistent patterns | Add 2-3 concrete examples with line numbers |
| Tasks >2.5 hours | Difficult to review, easy to drift | Split into tests + implementation + refactor |
| Negative framing | "Don't use X" is harder to follow | "ONLY use: Y, Z" |
| Buried rules | Model misses important constraints | Put at beginning AND end |
| No validation commands | Unclear when task is complete | Include explicit lint/test/typecheck commands |
| Allowing test modification | Tests weakened to pass implementation | "Revise implementation, not tests" |
| No drift policy | Small drifts compound | Explicit stop criteria and revert process |
| No commit checkpoints | Large uncommitted changes hard to debug | Commit after each task |
Integration with Other Skills
- implementation-planner: Apply these practices when generating plans
- implementation-plan-review: Validate plans against these practices
- business-requirements-interview: Ensure requirements align with these practices
- technical-requirements-interview: Technical specs should follow these practices
Examples
See examples/ directory for:
- Well-structured task with all best practices applied
- Before/after examples showing improvements
- Common mistakes and how to fix them
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/validkeys/sherpy/implementation-plan-best-practices">View implementation-plan-best-practices on skillZs</a>