--- name: prd description: "Generate a Product Requirements Document (PRD) for planning. Use when starting a new feature, project, or complex task. Triggers on: create a prd, write prd for, plan this feature, requirements for, spec out, prd for." --- # PRD Generator Create detailed Product Requirements Documents that integrate with Aeon Loop's planning system. --- ## Unified Workflow Available For a complete guided experience (PRD → Planning → Approval → Execution), use: ``` /aeon-flux ``` This skill (`/prd`) creates just the PRD. Use `/aeon-flux` for the full workflow. --- ## The Job 1. Receive a feature/task description from the user 2. Ask 3-5 essential clarifying questions (with numbered sub-options) 3. Generate a structured PRD based on answers 4. Save to `.planning/[task-slug]/prd.md` 5. **After PRD is created**, ask if user wants to continue with planning: - If yes → Guide them to run `/aeon-flux` to continue the workflow - If no → End here, they can manually run `/loop` later **Important:** Do NOT start implementing. Just create the PRD. --- ## Step 1: Clarifying Questions Ask only critical questions where the initial prompt is ambiguous. Focus on: - **Problem/Goal:** What problem does this solve? - **Core Functionality:** What are the key actions? - **Scope/Boundaries:** What should it NOT do? - **Success Criteria:** How do we know it's done? ### Format Questions Like This: ``` 1. What is the primary goal of this feature? 1.1. Improve user experience 1.2. Add new functionality 1.3. Fix existing issues 1.4. Other: [please specify] 2. What is the scope? 2.1. Minimal viable version 2.2. Full-featured implementation 2.3. Just the backend/API 2.4. Just the UI 3. What are the key constraints? 3.1. Must integrate with existing code 3.2. Greenfield implementation 3.3. Performance critical 3.4. Security critical ``` This lets users respond with "1.1, 2.2, 3.1" for quick iteration. --- ## Step 2: PRD Structure Generate the PRD with these sections: ### 1. Overview Brief description of the feature and the problem it solves. ### 2. Goals Specific, measurable objectives (bullet list). ### 3. User Stories Each story needs: - **Title:** Short descriptive name - **Description:** "As a [user], I want [feature] so that [benefit]" - **Acceptance Criteria:** Verifiable checklist of what "done" means Each story should be small enough to implement in one focused session. **Format:** ```markdown ### US-001: [Title] **Description:** As a [user], I want [feature] so that [benefit]. **Acceptance Criteria:** - [ ] Specific verifiable criterion - [ ] Another criterion - [ ] Tests pass ``` **Important:** - Acceptance criteria must be verifiable, not vague - "Works correctly" is bad - "Button shows confirmation dialog before deleting" is good ### 4. Functional Requirements Numbered list of specific functionalities: - "FR-1: The system must allow users to..." - "FR-2: When a user clicks X, the system must..." Be explicit and unambiguous. ### 5. Non-Goals (Out of Scope) What this feature will NOT include. Critical for managing scope. ### 6. Technical Considerations - Known constraints or dependencies - Integration points with existing systems - Performance requirements ### 7. Success Criteria How will success be measured? What does "done" look like? ### 8. Open Questions Remaining questions or areas needing clarification. --- ## Story-Sizing Discipline (Ralph Method) **Critical Rule:** Each user story must be completable in the **first 60% of a context window** (one loop iteration). ### The 60% Rule Stories should complete using roughly **60% of a subagent's context window**: - **20%** - Context loading (checkpoint, attention, patterns, plan files) - **60%** - Actual work (implementation, testing, state updates) - **20%** - Buffer (errors, unexpected complexity, cleanup) This ensures stories never hit context limits and have room for error recovery. ### Right-Sized Stories (GOOD - fit in 60%) - Adding a database column with migration (~30 lines of code) - Creating a single UI component (~50 lines) - Implementing one API endpoint with tests (~80 lines) - Adding a filter dropdown to a list (~40 lines) - Writing tests for one module (~60 lines) ### Too Large - Must Split (BAD - would exceed 60%) - "Build entire dashboard" → Split into individual widgets (5-10 stories) - "Implement authentication system" → Split into US-001: Register, US-002: Login, US-003: Logout, US-004: Sessions (4 stories) - "Refactor entire API" → Split by endpoint or module (10+ stories) ### The 2-3 Sentence Rule **If you cannot describe the change in 2-3 sentences, it is too big.** This is a quick heuristic. If you need a paragraph to explain it, split it. ### Estimating 60% of Context For Sonnet 4.5 (~200K context window): - Target ~120K tokens for story completion - Roughly 400-600 lines of code read + written - Or 2-3 files modified with tests If a story would require: - Reading >10 files - Writing >200 lines - Touching >5 files - Multiple complex algorithms → It's too big. Split it. ### Mandatory Acceptance Criteria Every story MUST include at minimum: - [ ] Typecheck passes (for TypeScript/typed projects) - [ ] Tests pass (if tests exist for this area) - [ ] Verify in browser (for UI changes) --- ## Writing for Implementation The PRD reader may be an AI agent executing via `/loop`. Therefore: - Be explicit and unambiguous - Avoid jargon or explain it - Provide enough detail to understand purpose and core logic - Number requirements for easy reference - Use concrete examples where helpful - Include file paths when known --- ## Output - **Format:** Markdown (`.md`) - **Location:** `.planning/[task-slug]/` - **Filename:** `prd.md` After creating the PRD, also create/update `task_plan.md` in the same directory with phases derived from the user stories. ### State Block (Machine-Parseable Progress) After the user stories section, add a state block for progress tracking: ```markdown ``` This block: - Lives inside `prd.md` (no separate JSON file needed) - Is updated by Claude when stories complete (`passes: false` → `passes: true`) - Is parsed by hooks for progress tracking - Preserves human readability (inside HTML comment, invisible when rendered) **Update protocol:** After completing a story, update its `passes` field: ```bash sed -i '/id: US-001/,/notes:/{s/passes: false/passes: true/}' .planning/*/prd.md ``` --- ## Integration with Aeon Loop After generating the PRD: 1. Create `.planning/[task-slug]/prd.md` with the full PRD 2. Create `.planning/[task-slug]/task_plan.md` with phases based on user stories 3. Inform user they can run `/loop "[task]" --done "COMPLETE"` to execute The `/loop` command will use the PRD and task_plan.md to guide implementation. --- ## Example PRD ```markdown # PRD: User Authentication System ## Overview Implement user authentication with login, logout, and session management. Users should be able to securely access their accounts and have their sessions persist across browser restarts. ## Goals - Secure user authentication with password hashing - Session persistence using secure cookies - Clear login/logout user flow - Protection against common auth vulnerabilities ## User Stories ### US-001: User Registration **Description:** As a new user, I want to create an account so that I can access the application. **Acceptance Criteria:** - [ ] Registration form with email and password fields - [ ] Password minimum 8 characters with complexity requirements - [ ] Email uniqueness validation - [ ] Success redirects to login page - [ ] Tests pass ### US-002: User Login **Description:** As a registered user, I want to log in so that I can access my data. **Acceptance Criteria:** - [ ] Login form with email and password fields - [ ] Invalid credentials show error message (no info leak) - [ ] Successful login redirects to dashboard - [ ] Session cookie set with secure flags - [ ] Tests pass ### US-003: User Logout **Description:** As a logged-in user, I want to log out so that I can secure my session. **Acceptance Criteria:** - [ ] Logout button visible when authenticated - [ ] Clicking logout clears session - [ ] Redirects to login page - [ ] Tests pass ### US-004: Session Persistence **Description:** As a user, I want my session to persist so I don't have to log in every time. **Acceptance Criteria:** - [ ] Session survives browser restart - [ ] Session expires after 7 days of inactivity - [ ] Remember me option for 30-day sessions - [ ] Tests pass ## Functional Requirements - FR-1: Hash passwords using bcrypt with cost factor 12 - FR-2: Store sessions in database with expiration timestamp - FR-3: Set HttpOnly, Secure, SameSite=Strict on session cookies - FR-4: Rate limit login attempts (5 per minute per IP) - FR-5: Log authentication events for audit trail ## Non-Goals - Social login (OAuth) - future enhancement - Two-factor authentication - future enhancement - Password reset via email - separate PRD - User profile management - separate PRD ## Technical Considerations - Use existing database connection pool - Session table needs index on token and user_id - Consider Redis for session storage if scale requires ## Success Criteria - Users can register, login, and logout without errors - Sessions persist correctly across browser restarts - No security vulnerabilities in OWASP top 10 - All tests pass ## Open Questions - What should session timeout be? (defaulting to 7 days) - Should we support "remember me" from launch? ``` --- ## Checklist Before saving the PRD: - [ ] Asked clarifying questions with numbered sub-options (1.1, 1.2, etc.) - [ ] Incorporated user's answers - [ ] User stories are small and specific (2-3 sentence rule) - [ ] Each story has mandatory acceptance criteria (typecheck, tests, browser verify) - [ ] Functional requirements are numbered and unambiguous - [ ] Non-goals section defines clear boundaries - [ ] Added STATE block with all stories (passes: false) - [ ] Saved to `.planning/[task-slug]/prd.md` - [ ] Created corresponding `task_plan.md` with phases