rails_claude_skills 0.1.0

data/lib/generators/claude/skills_library/refine-requirements/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: refine-requirements
+description: Refine and clarify feature requirements by asking targeted follow-up questions, then update or create tasks based on answers. Use after initial planning when requirements need clarification, or when the user mentions "refine", "clarify", "more details", or "questions".
+allowed-tools: Read, AskUserQuestion, TodoWrite
+---
+
+# Refine Requirements Skill
+
+Ask targeted follow-up questions to clarify ambiguous requirements and update implementation tasks based on the answers. Used after initial feature planning to ensure comprehensive understanding before coding.
+
+## When to Use This Skill
+
+Use this skill when:
+- After running `/plan-feature` and need more clarity
+- User says "I need to clarify some things"
+- Requirements seem ambiguous or incomplete
+- User mentions "refine", "more details", "questions"
+- Before starting implementation to reduce rework
+
+## Instructions
+
+Follow these steps to refine requirements:
+
+### Step 1: Understand Current Context
+
+First, gather context about what's been planned:
+
+1. Check if TodoWrite has active tasks (indicates planning already happened)
+2. If tasks exist, read them to understand the feature scope
+3. If no tasks, ask user: "What feature are you refining requirements for?"
+
+Present current understanding:
+```
+I can see you're planning [feature name] with [N] tasks. Let me ask some clarifying questions to refine the requirements.
+```
+
+### Step 2: Identify Gaps and Ambiguities
+
+Analyze the current plan for common gaps:
+
+**Data/Schema Questions:**
+- Missing field validations or constraints
+- Unclear relationships or associations
+- Missing indexes or performance considerations
+- Data migration or seeding needs
+
+**Business Logic Questions:**
+- Edge cases not covered
+- Validation rules unclear
+- State transitions undefined
+- Authorization rules ambiguous
+
+**UI/UX Questions:**
+- User workflows incomplete
+- Error handling unclear
+- Success/failure states undefined
+- Mobile vs desktop behavior
+
+**Technical Questions:**
+- Performance requirements unclear
+- Caching strategy undefined
+- Background job needs
+- Real-time updates needed?
+- API requirements
+
+### Step 3: Ask Targeted Questions
+
+Use AskUserQuestion to ask 3-5 focused questions based on the feature type.
+
+**Question selection strategy:**
+1. Refer to [reference.md](reference.md) for question templates by feature type
+2. Prioritize questions that will change implementation significantly
+3. Focus on gaps that could cause rework later
+4. Avoid questions already answered in the plan
+
+**Format questions clearly:**
+- One topic per question
+- Provide context for why you're asking
+- Offer common options when applicable
+- Use multiSelect when appropriate
+
+### Step 4: Analyze Answers
+
+After receiving answers, analyze impact:
+
+1. **New tasks needed?** - Do answers introduce new work?
+2. **Existing tasks change?** - Do answers modify planned approach?
+3. **Dependencies shift?** - Do answers change task ordering?
+4. **Scope change?** - Do answers significantly expand/reduce scope?
+
+### Step 5: Update or Create Tasks
+
+Based on answers, update the implementation plan:
+
+**If TodoWrite tasks exist:**
+- Use TodoWrite to update existing tasks with new details
+- Add new tasks if answers revealed additional work
+- Reorder tasks if dependencies changed
+- Mark tasks as pending that need revision
+
+**If no tasks exist:**
+- Create initial task list using TodoWrite
+- Include all details from the refinement conversation
+
+**Task updates should include:**
+- Specific details from answers (validation rules, UI states, etc.)
+- New acceptance criteria
+- Changed technical approach
+- Additional files to create/modify
+
+### Step 6: Present Refinement Summary
+
+Provide a clear summary of what changed:
+
+```
+## Requirements Refined
+
+### Questions Asked
+1. [Question 1]
+   - Answer: [Summary]
+   - Impact: [What this changes]
+
+2. [Question 2]
+   - Answer: [Summary]
+   - Impact: [What this changes]
+
+### Changes to Implementation Plan
+
+**Tasks Updated:**
+- Task 3: Added email uniqueness validation
+- Task 5: Changed to use Turbo Stream instead of full page reload
+
+**New Tasks Added:**
+- Task 7: Implement password strength indicator
+- Task 8: Add "remember me" functionality
+
+**Technical Approach Changes:**
+- Using Devise instead of custom auth
+- Adding Kredis for session storage
+- Implementing rate limiting with Rack::Attack
+
+### Updated Scope
+- Original: [X] tasks
+- Refined: [Y] tasks
+- Effort change: [increased/decreased/same]
+
+### Ready to Proceed?
+The implementation plan has been updated based on your answers. Review the updated tasks and let me know if you'd like to proceed or need further refinement.
+```
+
+## Question Strategies by Feature Type
+
+For detailed question templates, see [reference.md](reference.md).
+
+**Quick reference:**
+
+### Authentication Features
+Focus on: method, security, sessions, recovery, MFA
+
+### CRUD Features
+Focus on: validations, permissions, UI flows, real-time updates
+
+### Admin/Dashboard Features
+Focus on: metrics, filters, exports, access control
+
+### API Features
+Focus on: versioning, authentication, rate limiting, documentation
+
+### Background Jobs
+Focus on: triggers, frequency, error handling, monitoring
+
+## Best Practices
+
+**Do:**
+- ✅ Ask questions that will significantly impact implementation
+- ✅ Reference existing Rails patterns in the project
+- ✅ Prioritize security and performance clarifications
+- ✅ Focus on edge cases and error scenarios
+- ✅ Consider mobile vs desktop differences
+- ✅ Update tasks with specific, actionable details
+
+**Don't:**
+- ❌ Ask questions already answered in the plan
+- ❌ Ask more than 5 questions at once (overwhelming)
+- ❌ Ask vague questions without context
+- ❌ Skip updating tasks after getting answers
+- ❌ Make assumptions - clarify instead
+- ❌ Ignore technical debt or performance implications
+
+## Integration with Other Skills
+
+**After plan-feature:**
+```bash
+/plan-feature "Add commenting system"
+# ... initial plan created ...
+/refine-requirements
+# ... asks follow-up questions, updates tasks ...
+```
+
+**Before create-task-files:**
+```bash
+/plan-feature "Add commenting system"
+/refine-requirements  # Clarify first
+/create-task-files    # Then export
+```
+
+**Standalone:**
+```bash
+/refine-requirements
+# Asks: "What feature are you refining?"
+# Creates tasks based on detailed answers
+```
+
+## Examples
+
+For real-world examples of requirement refinement sessions, see [examples.md](examples.md).
+
+## Output
+
+Always use TodoWrite to update or create tasks. Ensure:
+- Tasks include specific details from answers
+- Acceptance criteria updated with new requirements
+- Technical approach reflects refined understanding
+- Dependencies and ordering adjusted if needed
+
+This skill ensures thorough requirement gathering, reduces implementation rework, and catches edge cases early in the planning phase.

data/lib/generators/claude/skills_library/refine-requirements/references/examples.md

@@ -0,0 +1,344 @@
+# Requirement Refinement Examples
+
+Real-world examples of requirement refinement sessions showing how follow-up questions lead to better implementation plans.
+
+## Example 1: Blog Post Commenting System
+
+### Initial Plan (from /plan-feature)
+
+**Feature:** Add commenting system for blog posts
+
+**Initial Tasks:**
+1. Create Comment model with migration
+2. Add CommentsController with CRUD actions
+3. Build comment form partial
+4. Display comments list
+5. Add tests
+
+### Refinement Session
+
+**Questions Asked:**
+
+**Q1: Comment Threading**
+- Header: "Nesting"
+- Question: "Should comments support nested replies (threaded discussions) or stay flat?"
+- Options:
+  - Flat comments only (simpler)
+  - One level of nesting (reply to comments)
+  - Unlimited nesting depth (full threading)
+
+**Answer:** One level of nesting
+
+**Q2: Moderation**
+- Header: "Moderation"
+- Question: "How should comment moderation work?"
+- Options:
+  - Auto-publish all comments
+  - Admin approval required before publishing
+  - Auto-publish but allow flagging for review
+  - Spam detection with Akismet integration
+
+**Answer:** Auto-publish but allow flagging for review
+
+**Q3: Editing & Deletion**
+- Header: "Edit/Delete"
+- Question: "Can users edit or delete their comments after posting?"
+- Options:
+  - No editing or deletion
+  - Edit within 5 minutes of posting
+  - Edit anytime, show edit indicator
+  - Soft delete only (hide but preserve)
+
+**Answer:** Edit within 5 minutes, soft delete
+
+**Q4: Notifications**
+- Header: "Notifications"
+- Question: "Should users be notified of replies to their comments?"
+- Options:
+  - No notifications
+  - Email notifications (immediate)
+  - In-app notifications only
+  - Both email and in-app with user preference
+
+**Answer:** Both email and in-app with user preference
+
+### Updated Implementation Plan
+
+**New/Modified Tasks:**
+
+1. ✏️ **Updated:** Create Comment model with migration
+   - Add `parent_id` for one-level nesting
+   - Add `deleted_at` for soft deletes
+   - Add `edited` boolean flag
+   - Add `flagged` boolean and `flag_count` integer
+   - Add indexes: `parent_id`, `deleted_at`, `post_id + created_at`
+
+2. **New:** Add CommentNotificationPreference model
+   - Migration for user notification preferences
+   - Default to email + in-app enabled
+
+3. ✏️ **Updated:** Add CommentsController
+   - CRUD actions
+   - Add `flag` action for reporting
+   - Add edit action with 5-minute time check
+   - Add soft delete (update deleted_at)
+   - Add `replies` action for nested comments
+
+4. **New:** Add CommentNotificationJob
+   - Background job to send email notifications
+   - Check user preferences before sending
+   - Use ActionMailer
+
+5. ✏️ **Updated:** Build comment form partial
+   - Support reply context (parent comment)
+   - Show "replying to @username"
+   - Cancel reply button
+
+6. ✏️ **Updated:** Display comments list
+   - Show nested replies (indented)
+   - Show edit indicator if edited
+   - Hide deleted comments (show "[deleted]")
+   - Flag button for inappropriate content
+   - Edit button (only if < 5 minutes and owner)
+   - Delete button (owner only)
+
+7. **New:** Add in-app notification system
+   - Create Notification model
+   - Add notification bell UI component
+   - Mark as read functionality
+
+8. **New:** Add admin moderation dashboard
+   - List flagged comments
+   - Approve/delete actions
+   - Ban user capability
+
+9. ✏️ **Updated:** Add tests
+   - Test nested replies
+   - Test soft delete behavior
+   - Test edit time window
+   - Test flagging workflow
+   - Test notification delivery
+
+**Scope Change:**
+- Original: 5 tasks
+- Refined: 13 tasks
+- Effort: Significantly increased (but prevented rework)
+
+---
+
+## Example 2: User Authentication
+
+### Initial Plan
+
+**Feature:** Add user login with email/password
+
+**Initial Tasks:**
+1. Install Devise
+2. Generate User model
+3. Add login/logout routes
+4. Create login form
+5. Add tests
+
+### Refinement Session
+
+**Questions Asked:**
+
+**Q1: Registration Flow**
+"What's required for user registration?"
+- Email + password only
+- Email + password + name ✓
+- Email + password + name + profile photo
+- OAuth only (Google/GitHub)
+
+**Q2: Email Verification**
+"Should users verify email before accessing the app?"
+- No verification needed
+- Optional verification (can use app immediately) ✓
+- Required verification (can't login until verified)
+
+**Q3: Password Security**
+"What password security requirements?"
+- Basic (6+ characters)
+- Medium (8+ chars, mix of letters/numbers) ✓
+- Strong (10+ chars, uppercase, lowercase, numbers, symbols)
+
+**Q4: Session Management**
+"How should user sessions work?"
+- Standard session (logout on browser close)
+- Remember me checkbox (30 days) ✓
+- Always remember (persistent session)
+
+### Updated Implementation Plan
+
+**Changes:**
+- Added name field to User model
+- Added email confirmation columns
+- Added Devise confirmable module
+- Added password strength validator gem
+- Added remember_me checkbox to login form
+- Added welcome email on registration
+- Added email confirmation instructions email
+- Added profile name to navigation
+- Added tests for email confirmation flow
+- Added tests for password validation
+- Added tests for remember me functionality
+
+**Scope Change:**
+- Original: 5 tasks
+- Refined: 9 tasks
+
+---
+
+## Example 3: Admin Dashboard
+
+### Initial Plan
+
+**Feature:** Create admin dashboard to manage posts
+
+**Initial Tasks:**
+1. Add admin role to User model
+2. Create Admin::PostsController
+3. Build admin posts index view
+4. Add authorization checks
+5. Add tests
+
+### Refinement Session
+
+**Questions Asked:**
+
+**Q1: Metrics Display**
+"What metrics should the dashboard show?"
+- Just post count
+- Post count + user count + comment count ✓
+- Full analytics (views, engagement, trends)
+
+**Q2: Filtering**
+"How should admins filter posts?"
+- No filtering
+- By status (published/draft) ✓
+- By status + author + date range ✓
+
+**Q3: Bulk Actions**
+"Should admins be able to perform bulk actions?"
+- No bulk actions
+- Bulk delete only
+- Bulk publish/unpublish ✓
+- Full bulk edit capabilities
+
+**Q4: Activity Log**
+"Should admin actions be logged?"
+- No logging
+- Log in Rails logger only
+- Database audit log ✓
+- Database log + email notifications for critical actions
+
+### Updated Implementation Plan
+
+**Changes:**
+- Added dashboard homepage with metrics cards
+- Added counter caches for metrics
+- Added filtering form with status, author, date range
+- Added bulk action checkboxes
+- Added bulk controller actions
+- Added AdminAuditLog model
+- Added audit log viewer
+- Added Turbo Frames for inline editing
+- Added Stimulus controller for bulk selection
+- Extended test coverage for all features
+
+**Scope Change:**
+- Original: 5 tasks
+- Refined: 14 tasks
+
+---
+
+## Example 4: API Endpoint
+
+### Initial Plan
+
+**Feature:** Add JSON API for blog posts
+
+**Initial Tasks:**
+1. Create API::PostsController
+2. Add JSON serialization
+3. Add API routes
+4. Add tests
+
+### Refinement Session
+
+**Questions Asked:**
+
+**Q1: Authentication**
+"How should API clients authenticate?"
+- No authentication (public API)
+- API keys ✓
+- JWT tokens
+- OAuth 2.0
+
+**Q2: Versioning**
+"How should we version the API?"
+- No versioning
+- URL versioning (/api/v1) ✓
+- Header versioning
+- Query parameter versioning
+
+**Q3: Rate Limiting**
+"Should we rate limit API requests?"
+- No rate limiting
+- Basic rate limit (100 requests/hour per IP)
+- Tiered rate limits by API key tier ✓
+- Dynamic rate limiting based on load
+
+**Q4: Response Format**
+"What should API responses include?"
+- Just the data
+- Data + metadata (pagination, links) ✓
+- Data + metadata + HATEOAS links
+
+### Updated Implementation Plan
+
+**Changes:**
+- Added ApiKey model with generation and tiers
+- Added API authentication middleware
+- Added rack-attack for rate limiting
+- Added tier-based rate limit configuration
+- Added /api/v1 namespace
+- Added pagination with Kaminari
+- Added metadata in responses
+- Added API documentation with OpenAPI spec
+- Added rate limit headers in responses
+- Added API key management UI for admins
+- Added comprehensive API tests
+
+**Scope Change:**
+- Original: 4 tasks
+- Refined: 11 tasks
+
+---
+
+## Key Takeaways from Examples
+
+### Common Patterns
+
+1. **Initial plans are often too simple** - Missing edge cases, validation rules, and UX details
+2. **Security and performance are often overlooked** - Rate limiting, authorization, caching
+3. **User experience details matter** - Notifications, feedback, error handling
+4. **Admin/management tools needed** - Moderation, audit logs, bulk actions
+
+### Impact of Refinement
+
+- **Prevents rework** - Catches requirements early
+- **Improves quality** - Forces thinking about edge cases
+- **Sets expectations** - User knows full scope upfront
+- **Better estimates** - More accurate task breakdown
+
+### Best Questions to Ask
+
+1. **Edge cases** - What happens when X fails or is unusual?
+2. **Permissions** - Who can do what?
+3. **User experience** - How should this feel to use?
+4. **Performance** - How fast must this be?
+5. **Security** - What could go wrong?
+6. **Scale** - How many records/users/requests?
+
+Use these examples as templates for your own requirement refinement sessions.