Agent skill
review-spec
Review a spec document against codebase reality, identifying gaps and ensuring sound, robust implementations.
Install this agent skill to your Project
npx add-skill https://github.com/ferueda/agent-skills/tree/main/skills/review-spec
SKILL.md
Review the given spec document by analyzing both the spec AND the referenced codebase.
Process
- Read the spec - Understand goals, phases, and proposed changes
- Explore the codebase - Read files and code mentioned in the spec
- Analyze patterns - Identify existing patterns, conventions, and architecture
- Validate the plan - Ensure proposals align with codebase reality
- Identify issues - Find gaps, risks, and improvement opportunities
Review Dimensions
Evaluate across these areas (focus on what's relevant):
- Architecture: Component boundaries, data flow, API contracts, separation of concerns
- Feasibility: Implementation complexity, technology trade-offs, effort estimation
- Reliability: Error handling, retries, idempotency, graceful degradation
- Performance: Bottlenecks, caching, query patterns, scaling approach
- Security: Auth, data protection, input validation, audit logging
- Edge Cases: Null handling, limits, timeouts, race conditions, partial failures
- Testing: Testability, integration strategy, rollback considerations
Output Format
For each finding:
### [Finding Title]
**Category**: Architecture | Feasibility | Reliability | Performance | Security | Edge Case | Testing
**Severity**: Critical | High | Medium | Low
**Section**: [Spec section or phase]
**Issue**: [Clear problem description]
**Recommendation**: [Specific, actionable change]
**Rationale**: [Technical justification]
Guidelines
- Verify against code - Don't trust the spec blindly; check actual implementations
- Follow existing patterns - Recommendations should align with codebase conventions
- Be specific - Reference exact files, functions, and line numbers
- Prioritize - Order findings by severity and impact
- Challenge assumptions - Question decisions that lack justification
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
ferueda/agent-skills
create-plan
Create detailed implementation plans with thorough research and iteration. Use when the user asks to build a feature, create a plan, or specifically invokes this skill.
ferueda/agent-skills
summarize-work
Summarize work done in a spec/plan document.
ferueda/agent-skills
ask-questions
Clarify requirements before implementing. Do not use automatically, only when invoked explicitly.
ferueda/agent-skills
research-codebase
Research codebase comprehensively using parallel sub-agents. Use when the user asks to "research the codebase", "understand how X works", or "investigate Y".
ferueda/agent-skills
implement-plan
Implement a spec document phase-by-phase, writing robust idiomatic code that follows codebase patterns.
mattpocock/skills
edit-article
Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.
Didn't find tool you were looking for?